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.
## 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.
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:
| Name | Source | Source attribute |
_`email`_ | Attribute | `user.userprincipalname` |
_`first_name`_ | Attribute | `user.givenname` |
_`last_name`_ | Attribute | `user.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 **`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:
| Column Title | Column Title |
| **Name ID format** | EmailAddresss |
| **Application username** |
In the `Attribute Statements` section, configure the following three attributes:
| Name | Name format | Value |
_`email`_ | Basic | `user.email` |
_`first_name`_ | Basic | `user.firstName` |
_`last_name`_ | Basic | `user.lastName` |
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
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.