Enabling Single Sign-On with Microsoft Entra for administrator access

With Soapbox Engage, you have the ability to enable single sign-on (SSO) with Microsoft Entra ID (formerly Azure Active Directory) as the identity provider. This allows authorized Microsoft Entra users to log in to the Soapbox administrator using their organization's Microsoft account credentials.

This integration uses SAML 2.0.

Step 1: Create an Enterprise Application in Microsoft Entra

To set up single sign-on, you will first need to create a new Enterprise application in Microsoft Entra.

1. Sign in to the Microsoft Entra admin center using an account with Application Administrator or Cloud Application Administrator permissions.
2. Navigate to Entra ID > Enterprise apps > All applications.
3. Click New application.
4. Click Create your own application.
5. For the application name, enter Soapbox Engage.
6. Select Integrate any other application you don't find in the gallery (Non-gallery).
7. Click Create.
8. Once the application has been created, select Single sign-on from the left navigation menu.
9. Under Select a single sign-on method, select SAML.
10. On the Set up Single Sign-On with SAML page, locate Basic SAML Configuration and click the Edit (pencil) icon.
11. Enter the following information, replacing {your Soapbox domain} with the domain of your Soapbox Engage site:
    • Identifier (Entity ID): https://{your Soapbox domain}/saml/default-sp
    • Reply URL (Assertion Consumer Service URL): https://{your Soapbox domain}/saml/default-sp
    • Relay State: https://{your Soapbox domain}/administrator/index.php?option=com_login&task=saml
    • Sign on URL: Optional. Leave blank if administrators will initiate login from the Soapbox administrator page.
    • Logout URL: Leave blank.
12. Click Save.

Configure User Attributes and Claims

Next, configure Microsoft Entra to send the user's email address as the SAML identifier.

1. On the Set up Single Sign-On with SAML page, locate Attributes & Claims and click the Edit (pencil) icon.
2. Select Unique User Identifier (Name ID).
3. Configure the following:
   • Source attribute: user.mail
   • Name identifier format: Email address
4. Click Save.

IMPORTANT: Soapbox Engage identifies administrator accounts by their email address. Make sure the email address sent by Microsoft Entra matches the user's username in Soapbox Engage.

Microsoft Entra's User Principal Name (UPN) is not always the same as a user's email address. For this reason, we recommend using user.mail rather than the default user.userprincipalname attribute. If the user's Mail attribute is empty, Microsoft Entra may fall back to the UPN, so confirm that each administrator has the correct email attribute populated.

Configure SAML Signing

1. Return to the Set up Single Sign-On with SAML page.
2. Locate SAML Signing Certificate and click the Edit (pencil) icon.
3. Configure the following:
   • Signing Option: Sign SAML response and assertion
   • Signing Algorithm: SHA-256
4. Click Save.

For reference, here is an overview of the recommended Microsoft Entra SAML configuration:

Examples of custom and default Soapbox domains include:

• https://www.example.org/saml/default-sp
• https://act.example.org/saml/default-sp
• https://example.secure.nonprofitsoapbox.com/saml/default-sp

Step 2: Assign users or groups to your Application in Microsoft Entra

Once you have created your Enterprise application, you must assign the users or groups who should be permitted to access Soapbox Engage.

1. Navigate to Entra ID > Enterprise apps > All applications.
2. Select your new Soapbox Engage application.
3. Select Properties and confirm that Assignment required? is set to Yes. Click Save if you change this setting.
4. Select Users and groups from the left navigation menu.
5. Click Add user/group.
6. Select the Microsoft Entra users or groups you wish to grant access to Soapbox Engage.
7. Under Select a role, choose Default Access, if prompted.
8. Click Assign.

Repeat these steps for any additional users or groups.

Note: Assigning a user to the Microsoft Entra application does not automatically create a Soapbox Engage administrator account. Each user must also have an enabled user account in Soapbox Engage, as described in Step 5.

Group-based application assignments may require Microsoft Entra ID P1 or P2 licensing.

Step 3: Retrieve SAML Configuration Details from Microsoft Entra

Once you have created your application and assigned users, you will need to retrieve the Microsoft Entra configuration details to enter into Soapbox Engage.

1. Navigate to Entra ID > Enterprise apps > All applications.
2. Select your Soapbox Engage application.
3. Click Single sign-on from the left navigation menu.
4. Scroll down to the section labeled Set up Soapbox Engage.
5. Locate the following values:
   • Login URL
   • Microsoft Entra Identifier
6. Keep this page open, as you will need these values in the next step.
7. Scroll to the SAML Signing Certificate section.
8. Locate Certificate (Base64) and click Download.
9. Open the downloaded certificate file in a text editor. You will use its contents in the next step.

Step 4: Configure Single Sign-On for Microsoft Entra in Soapbox

To configure single sign-on for Microsoft Entra in Soapbox Engage:

1. Log in to your Soapbox administrator.
2. Go to Single Sign-On.
3. On the Service Provider Setup tab, for Enable Admin Single Sign-on, select Yes.
4. For Identity Provider Entity ID, enter the Microsoft Entra Identifier from the Microsoft Entra application configuration.
5. For Admin SAML Login URL, enter the Login URL from the Microsoft Entra application configuration.

6. For X.509 Certificate, paste the Base64-encoded certificate contents downloaded in Step 3.

   IMPORTANT: If your certificate includes the lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, copy only the certificate text between those lines. Do not include the BEGIN or END CERTIFICATE lines in the Soapbox X.509 Certificate field.

7. Click the Login Settings tab.
8. Under Administrator Options, for Login Button Text, enter the text of the hyperlink that will appear on the administrator login page. We recommend Login with Microsoft.
9. For Login Options, choose whether administrators can log in using:
   • Either their Soapbox credentials or their Microsoft Entra credentials.
   • Only their Microsoft Entra credentials.
10. Click Save.

Single sign-on has now been configured for your Soapbox administrator.

Recommendation: When initially configuring SSO, allow both login methods until you have successfully tested Microsoft Entra authentication. After confirming that SSO works, you can change the setting to require Microsoft Entra authentication if desired.

Step 5: Add users to the User Manager in Soapbox

To access the Soapbox administrator using Microsoft Entra credentials, an individual must have an enabled user account in Soapbox with a username matching the email address sent by Microsoft Entra.

To create accounts in Soapbox:

1. Go to the User Manager.
2. Click New to create a user.
3. For First Name, enter the first name of the user.
4. For Last Name, enter the last name of the user.
5. For Username, enter the email address associated with the user's Microsoft Entra account.
6. For E-mail, enter the same email address.
7. For New Password, enter a strong, unique password. This password will not be used when logging in via Microsoft Entra single sign-on.
8. For Verify Password, re-enter the password.
9. For Group, under Public Back-End, select either Manager or Administrator. Administrators can create and edit users, while Managers cannot.
10. Click Save.
11. Repeat for each user you wish to grant access to the administrator.

Testing Microsoft Entra Single Sign-On

Once both Microsoft Entra and Soapbox Engage have been configured, we recommend testing the integration before requiring all users to authenticate through Microsoft Entra.

1. Open a new private or incognito browser window.
2. Navigate to https://{your Soapbox domain}/administrator.
3. Click Login with Microsoft, or the custom login text you configured in Step 4.
4. You should be redirected to Microsoft's authentication page.
5. Sign in using the Microsoft account assigned to the Soapbox Engage Enterprise application.
6. Complete any multifactor authentication requirements configured by your organization.
7. After successful authentication, you should be redirected to the Soapbox administrator.

If authentication fails, verify that:

• The Microsoft Entra user is assigned to the Enterprise application.
• The user's Soapbox username matches the email address sent in the SAML Name ID.
• The Identifier and Reply URL values match your Soapbox domain exactly.
• The Microsoft Entra Identifier and Login URL were copied into the correct Soapbox fields.
• The X.509 certificate is the active SAML signing certificate and was copied correctly.
• The Soapbox user account is enabled and has appropriate administrator permissions.

Once testing is successful, your organization can use Microsoft Entra to authenticate authorized Soapbox Engage administrators.