Bloomreach Engagement Single Sign-On

As you have more internal users, managing access and keeping only active users start to be a more and more challenging task. The typical way to solve this issue is centralized identity management. The most common ones you might be familiar with are Azure Active Directory and Okta. However, with this new SSO feature, which is now available for multi tenant instances, you can manage access to the application for your employees while specific permissions can be managed directly from the application.

🚧

SSO before the 1.214 release

Please remember that this is a new version of our SSO login method used for authentication. If you are using the version before release 1.214, refer to this article for more details on it!

📘

Identity domain

The identity domain supports Bloomreach Engagement Single Sign-On. Please read this article to find out more about what it is and how to check who is part of your identity domain.

👍

Read up on how we enhanced Single Sign-On to include Authorization as well in our article.

How does it work?

Bloomreach Engagement Single Sign-On is an authentication method for your users. The Single Sign-On can serve as an additional method but it can also be set up as the only method to log in. You can integrate it with any Identity Provider that supports SAML 2.0 standards. However, you can still use your Google login information to access your account if you want to.

📘

The SSO login module is an additional-cost feature. To enable it, contact your Customer Success Manager (CSM)

📘

We have tested the integrations with Okta and Microsoft Azure Active Directory and we provide support only for those two.

Adding your users

First, your users have to be invited to the project. Then they can choose the login method they like. This applies to your new users. If you have existing users, they can choose the Single Sing-On method for the particular account they want to use to log into the project. Please remember that the user has to belong to the account with the SSO enabled. For example, if a user is invited to more accounts on your instance and SSO is enabled for only one of those accounts, SSO authentication works only for that account as settings of different accounts are not affected.

🚧

Remember that one user can have only one SSO enabled per account, and the user belongs to the account where they have been invited first.

General settings of the SSO method

To access the implementation of the new SSO method, you have to go to Settings > Account settings. Here, you can enable the feature. Then when SSO is enabled, you can configure Okta or Azure Active Directory to provide the authentication for the Engagement app. Make sure that you have an admin role assigned as it is the requirement for this configuration.

As for managing the permissions of certain roles in your project, you can manage them directly through Engagement, and there is no need to set up anything within Azure/Okta. The custom roles can be used for access management here, too.

Setup Guides

Setting up Azure Active Directory

Step 1:

In your Azure Active Directory dashboard, go to Enterprise Applications from the "Manage" menu on the left side.

Here, you would add the application you want to use by clicking on +New application and then +Create your own application.

Step 2:

In the opened modal window, fill in a name for your application, e.g. Bloomreach Engagement in this case, and choose Integrate any other application from the list of options. After that, submit the form to create the application.

Step 3:

We need to configure the newly created application for the SSO. From the left-side "Manage" menu, select Single sign-on and then SAML as the single sign-on method you want to use from the option tiles provided.

Step 4:

Now you’ll need to provide Azure AD with information from Bloomreach Engagement. Switch over to your Bloomreach Engagement application and navigate to Account Settings > Access management > Single sign-on.

Here, you should enable the integration and download the generated Service provider metadata. Store the file, e.g. as “service-provider-metadata.xml”, as you will need it in the next steps.

Step 5:

You can switch back to your Azure AD dashboard. Select Upload metadata file and choose the XML file you have just downloaded from Bloomreach Engagement.

After submitting the metadata file for the upload, you will be presented with a modal window with Basic SAML Configuration extracted from the metadata file. Go ahead and Save the configuration.

Step 6:

Now, the list of different steps would appear in the Azure Active Directory. Go directly to the second one called "Attributes & Claims" and click on the Edit button.

After that, a new edit window is opened. First, you should remove all Additional claims as these are the default claims created by Azure. Leave the Required claim untouched. You will need to configure new claims for Bloomreach Engagement instead by using the + Add new claim option.

Configure the following claims according to the table below:

📘

Note:

The email addresses in the user.userprincipalname attribute should be able to receive emails. If your users are not able to receive emails on that address, please use another unique attribute (e.g. user.mail) for email claim and for the Unique User Identifier (Name ID) claim.

You can optionally also provide a phone claim for each user, if you have the data available (e.g. in user.mobilephone attribute).

After following all those steps, your Attributes & Claims should look like the example below:

🚧

Please make sure that additional claims are in exactly the same format as shown in the picture above. We suggest removing default values and creating them from the scratch.

Step 7:

Now we will need to finish the service provider configuration on the Bloomreach Engagement side. You should be back in the opened window with the list of different steps. Go to the third one called "SAML Signing Certificate" and copy the "App Federation Metadata URL" to the clipboard as shown below.

After that, switch over to Bloomreach Engagement where you paste the address to the "Metadata URL" field in the Identity provider metadata section and click on Apply URL. If everything is configured properly, you should see a confirmation that the metadata contains valid Single-sign on URL and that “Microsoft Azure Federated SSO” Encryption/Signing certificates are not expired:

Save it and then navigate to Account Settings > Security > Authentication settings. There you can select Single Sign-On as the allowed authentication method. You can also disable other methods if you wish to use the enforced SSO for your users.

Lastly, save all the changes. From now on, all your existing Bloomreach Engagement users, that you assign to the application in Azure Active Directory, will be able to log in to Bloomreach Engagement via Azure AD Single sign-on.

Setting up Okta SSO

Step 1:

In your Okta administration dashboard, go to Applications and click on Create App Integration.

Here, select SAML 2.0, as the Sign-in method in the opened modal window and continue by clicking on the Next button.

Then you can set the name and icon for your new application and continue to the next step.

Step 2:

Now you’ll need to provide Okta with information from Bloomreach Engagement.
Switch over to your Bloomreach Engagement application and navigate to Account Settings > Access management > Single sign-on.

Enable the integration and click on Show configuration in the Service provider metadata section.

The new window will appear. Unfortunately, Okta currently does not support automatic configuration of the application via the service provider metadata file, so you will need to copy the required values from the Service Provider Configuration window to Okta.

First, copy the Single Sign On URL value to the Single sign on URL field in Okta configuration.

Now copy the Entity ID value to the Audience URI (SP Entity ID) field in Okta configuration.
That’s all you need from the Service provider configuration window, the rest of the configuration can be set directly in the Okta dashboard.

Step 3:

Now you can switch back to the Okta dashboard and continue with the second step in the dashboard called 2. Configure SAML.

Set the following fields to the given values:

In the Attribute Statements section, configure the following three attributes:

Here is an example of how the configuration should look like:

You can also optionally provide a phone attribute for each user if you have the data available (e.g. in user.primaryPhone attribute).

After filling out the configuration as required, you can continue to the next step called "Feedback". Now, the configuration of the application on the Okta side is finished.

Step 4:

On the Application settings page in Okta, in the Sign On tab, scroll down to the "SAML Signing Certificates" section. Find the active certificate and click on Actions > View IdP metadata as shown below:

The metadata XML file will be opened in a new tab. Copy the URL to your clipboard.

Step 5:

Now switch over to Bloomreach Engagement, paste the address to the Metadata URL field in the "Identity provider metadata" section and click on Apply URL. If everything is configured properly, you should see a confirmation that the metadata contains valid Single-sign on URL and Encryption/Signing certificates that are not expired:

Save it and then navigate to Account Settings > Security > Authentication settings. There you can select Single Sign-On as the allowed authentication method. You can also disable other methods if you wish to use the enforced SSO for your users.

You can go ahead and Save the changes. From now on, all your existing Bloomreach Engagement users that you assign to the application in Okta will be able to log in to Bloomreach Engagement via Okta Single sign-on.

Limitations

🚧

• Users with SSO authorization cannot be invited, users without SSO authorization have to be invited into the Engagement application.
• SSO authorization will assign user roles during the login process. If there is a role change, the authentication process can take up to a minute.
• When a user chooses SSO for the authentication, Bloomreach 2FA/MFA is not used.
• There is only one SSO provider enabled per account.
• One user can only be managed by one SSO application per instance. See the native account.