Bloomreach Engagement Single Sign-On

This feature is in BETA version.

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 shared instances as well, you can manage the 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!

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.

📘

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.

770770

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

646646 547547

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.

573573

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.

13621362

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.

13891389

Step 5:

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

13731373

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.

845845

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.

777777

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.

807807

Configure the following claims according to the table below:

NameSourceSource attribute
emailAttributeuser.userprincipalname
first_nameAttributeuser.givenname
last_nameAttributeuser.surname

📘

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:

776776

🚧

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 clipboard as shown below.

765765

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:

13951395

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.

15911591

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 login 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.

719719

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

949949

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.

13891389

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.

10751075

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 Okta dashboard and continue with the second step in the dashboard called 2. Configure SAML.

Set the following fields to the given values:

Name ID formatEmailAddresss
Application usernameEmail

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

NameName formatValue
emailBasicuser.email
first_nameBasicuser.firstName
last_nameBasicuser.lastName

Here is the example how the cofiguration should look like:

741741

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 down below:

10251025

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

958958

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:

13951395

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.

15911591

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 login to Bloomreach Engagement via Okta Single sign-on.

Limitations

🚧

  • The SSO method can be used only for authentication (no roles assignment).
  • Users still need to be invited and accept the invitation.
  • 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 per instance.