❗️

New method available

This article is only applicable if your account has set up the SSO before the 1.214 release and is only available for Private/Exclusive instances!

If your account has set up the SSO after the 1.214 release, you are using the new SSO method, please refer to the new article for more information!

Private/Exclusive Instance required

For large enterprises, it is difficult to manage employee access, permissions, and resources in multiple places. We provide our Bloomreach Engagement SSO to solve the problem by communicating with your identity provider.

When logging in, Single Sign-On (SSO) removes the need to type in passwords as your identity will be provided and checked to provide access only to authorized users. The main benefit is that SSO prevents the risks created by poor password management or the risks of phishing. Moreover, it provides centralized access management which allows you to have full control of who has access to the application.

This works by propagating user groups with a SAML 2.0 message which matches the groups with permissions configured in Bloomreach Engagement. This ensures authenticated and authorized access to Bloomreach Engagement for both internal and external users. Federated Identity Management works with all identity providers that support the SAML 2.0 standard.

For SSO we use Security Assertion Markup Language (SAML) which is a general standard for logging users into the applications. SSO transfers the user’s identity from one place (the identity provider) to another (Bloomreach Engagement). This is done through an exchange of digitally signed XML documents.

The flow in more detail:

1. The user is logged into a system that acts as an identity provider and wants to sign in to Bloomreach Engagement app
2. Bloomreach Engagement app identifies the user’s origin (by application subdomain and user IP address) and redirects the user back to the identity provider, asking for authentication
3. The user either has an existing active browser session with the identity provider or establishes one by logging into the identity provider
4. The identity provider builds the authentication response in the form of an XML-document containing the user’s username or email address and groups and permissions, signs it using an X.509 certificate, and posts this information to Bloomreach Engagement
5. Bloomreach Engagement retrieves the authentication response and validates it using the certificate fingerprint
6. The identity of the user is established and the user is provided with access

As an example, James is trying to log into the Bloomreach Engagement Application. When he logs in he is asked to confirm his identity through an additional security layer. Once Bloomreach Engagement has identified James, he is granted access.

Federated Identity Management for SSO

Required configuration parameters

• Entity ID/Issuer ID - a unique identifier of SSO connection (ie sso1).
• Login URL - the URL path of where to redirect for login. Authentication Request Message target URL. HTTP-Redirect binding only.
• Identity provider certificate - X.509 certificate. Used for signing/encrypting messages, assertions or metadata. Multiple certificates can be provided.
  *Metadata file or metadata endpoint to fetch the whole configuration.

Other requirements

• Bloomreach Engagement requires assertions to be signed (<saml:Assertion> elements)
• Every SAML request must include following attributes:
  • username - a unique user identifier (If not provided, a user won't be created in application)
  • email - user’s email address (If not provided, the user won't be created in application)
  • permissions_v1 (If not provided, the user will have no access)
• The NameId parameter of the SAML request has to match the value in the username field

What Bloomreach Engagement provides

Bloomreach Engagement (service provider) provides a metadata file/endpoint. The ServiceProvider metadata endpoint/file contains:

• entityId
• X.509 certificates for signing/encrypting messages and assertions
• AssertionConsumerService endpoint - “login endpoint”
• AttributeConsumingService configuration - required attributes
• Organization and contact person details

Formatting data in SAML

Required: username

Username might be string, number basically identifier of the user in your system.

<saml:AttributeStatement>
  <saml:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">johnsmith</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Required: email

The email address of the user.

<saml:AttributeStatement>
  <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">[email protected]</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Required: permissions

Permissions are versioned where v{number} is the number of versions. The first version of permissions is labeled as “permissions_v1”.

You have to follow this format of permissions:

project.<project_slug>.<permission>.<access>
	- for project-level access
account.<account_slug>.<permission>.<access>
	- for account-level access

Project slug can be found in the URL, while you are logged in the application (example: https://app.exponea.com/p/exponea-demo-e-shop/home => project slug = exponea-demo-e-shop)

Account slug is not available in an interface right now.

Example:
The user has access to Bloomreach Engagement project with the slug “project1”:

<saml:AttributeStatement>
<saml:Attribute Name="permissions_v1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml:AttributeValue xsi:type="xs:string"xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.analyses.write</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.campaigns.execute</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.export.true</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">project.project1.project.admin</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>

In a case of multi-value permissions like campaigns “Read, Write, Execute” you have to specify the highest value of permissions as follows:

• Read,Write,Execute => execute
• Read,Write => write
• Read => read

Optional: User attributes

User attributes are not required, but it is highly recommended to provide this information for better user experience in application.

List of attributes: first_name, last_name, phone

<saml:AttributeStatement>
  <saml:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
	<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">John</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
	<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Doe</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="phone" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
	<saml:AttributeValue xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">+421900123456</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

📘

All users will be created as a “regular user” type. Instance Manager user types are not supported via SSO.

Migration phase

The migration phase consists of 5 steps. The phase should offer comfortable testing of SSO configuration, and there should be no outage on the instance - existing users should not be kicked off when SSO is enabled.

1. Username & SSO (Testing SSO configuration)

• Users can log into APP at the same time with SSO, Username, Social login. But once you log in with SSO and User with the same username exists already in the application, this user is automatically replaced. This user from this moment can only log in only via SSO.
• Superadmins are not automatically replaced. First of all, you need to delete the super admin and then login via SSO

2. Disabled invitation & registrations (transition phase)

• I can still log in with Username & SSO at the same time
• All invitations to an Accounts/Projects are disabled.
• All registration of user through Administration is disabled

3. SSO only (Final phase)

• You can log in only with SSO

Configuration

invisible_to_users - SAML2 is configured, but not visible to users (no Login with SSO button).
as_additional_method - SAML2 is available as an additional login method. The user can log in with all methods interchangeably.
enforced_once_used - SAML2 enabled simultaneously with other login methods. Invitations still enabled. Once a user logs in via SAML2, they cannot log in with any other methods.
enforced_for_new_users - SAML2 required for new users, existing users can log in through other methods. Invitations are disabled.
enforced_for_everyone - SAML2 login only. No invitations or other login methods allowed.

🚧

Please note that if you select enforced_for_new_users or enforced_for_everyone, only you will be ever able to give access to your account.

As a result, our customer support team would not be able to access your application and give their usual level of service. If you need support, agents will operate with screenshots provided by you.

Choosing one of these options unless necessary may become troublesome if you have a serious issue or downtime.

Full list of possible permission settings

If a user has a permission with a default value, this does not need to be defined explicitly.

🚧

Stand-alone roles

Each user must have at least one stand-alone role to be able to access a project. The list of permissions below contains the full list of roles that can be assigned via SSO. All of them are stand-alone roles except for Personal Data Viewer which should be assigned along with another stand-alone role(s).

Account scope

Attribute value format: account.<account-slug>.<permission>.<access>

Project scope

Attribute value format: project.<project-slug>.<permission>.<access>

📘

Instance scope permissions are not supported via SSO.