Configure SAML Integration for Single Sign-On

This article will help you:
- if you have some knowledge of SSO technologies 
- if you want to set up and integrate BRYTER with technologies using SAML

What is SAML?

SAML (Security Assertion Markup Language) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider (your single sign-on system) and a service provider (BRYTER).

Please note that this is a premium feature which needs to be enabled by your dedicated customer success manager. For further information, please reach out to your BRYTER Customer Success Manager or support@bryter.io. Additional pricing may apply.

BRYTER SAML integration for single sign-on

After the SAML integration is configured all users from the connected identity provider can login to BRYTER. Only users with a mapped role in your identity provider will be get a role in BRYTER and count towards your user quota. Attributes (first name, last name and email address) and roles will be mapped on every login, which means information will be updated and users leaving your organization won't be able to login anymore.

❗️This means that BRYTER admins cannot create users or assign roles within the BRYTER Admin console. This needs to be done exclusively by the administrators of your identity provider.

• For more guidance on how to set up the SAML integration in Azure AD, please refer to our article ⚙ How to setup single sign-on (SSO) with SAML integration and Azure AD
• For more guidance on how to set up the SAML integration in ADFS, please refer to our article Single sign-on (SSO) with SAML integration and Active Directory Federation Services (ADFS)

Be aware...

The configuration requires two metadata.xml files:

• Service Provider metadata, that you download from the BRYTER SAML Integration page; and
• Identity Provider metadata that you download from your identity provider.

Data from each of these files is combined in a new IdP configuration.

The method used to log in/log out must be set to HTTP-Post.

If you have existing BRYTER user accounts, to retain their existing data, be sure to create an exact match between their email addresses and the email claims. If the email addresses don’t match, then logging in via SSO for the first time will create a new user account (with a new email address) that will have no association with the original BRYTER user account or access to its data.

To test the integration, you’ll need three different user accounts: one with the role User, one Author, and one Admin.

SAML integration page

You can edit an existing integration, check configuration, or create a new IdP in the SAML Integration page in the Admin Console.

Clicking on any of the intuitively-titled links or buttons will take you to further pages to add or edit configuration data.

The SAML integration process

Complete these steps, via the SAML Integration page, to configure SAML for your organization.

1. Create Identity provider

💡You cannot edit the value in the IdP Identifier field once you click the Create identity provider!

1. Select "SAML Integration" in the Admin Console.
2. Click the New Identity Provider button. The New identity provider page is displayed.
3. Enter values into the Identifier and Name fields.❗ Please note that you cannot change the identifier later.
   
4. Click the Create identity provider button. The new IdP will display in the SAML integration page.

2. Download the BRYTER SAML Service Provider metadata.xml file

Select the Download metadata.xml link, displayed in the Actions column alongside the new IdP name.

The file will contain this default information:

3. Update the IdP configuration in your IdP’s metadata.xml file in the Edit identity provider page in the Bryter Admin Console.

💡 See your IdP’s support content to learn more about their metadata.xml file and how to download it.

1. Select the Edit option for the new IdP.
2. Enter appropriate values into these fields:
   
   

   Login URL	This information is usually found in the SingleSignOnService tag in the metadata file
   Certificate (base 64)	The X.509 certificate for signing (not for encryption). Usually located in the X509Certificate tag as a child of the KeyDescriptor use="signing" tag in the metadata file. Do not include header (----BEGIN) or footer data.
   XML signature key name	Depends on your identity provider. Usually: CERT_SUBJECT is used by Microsoft AD FS; KEY_ID is used by Keycloak and other Red Hat-based identity providers The NONE option may work for other IdPs
   Logout URL	Optional. Usually located in the SingleSignOutService tag in the metadata file .
   First name claim
   Last name claim
   Email claim	Must match any existing email addresses to preserve user data.

3. Click the Update Identity provider button

4. Test the login and attributes mapping

If you can’t log in successfully, check:

• the Login URL, Certificate (base 64) and XML signature key name; and
• that the information displayed on the Show the mapped SAML claims pop-up is correct.
  Don’t forget — no role is mapped yet!

In the SAML Integration window, next to the name of your new IdP, click the link Open this link in private mode to test login.
You should be logged into the test account.

💡 If the Update Account Information page is displayed, do not change the values via this modal. Go to the Edit identity provider page, and amend the values in the fields until you can log in successfully.

5. Configure role mapping

BRYTER currently supports three user classifications: 🔐 BRYTER user classification | role permissions

1. In the SAML Integration page, next to the name of your new IdP, select Role Mapping from the Actions column.
   
   
2. Edit the the default values, if required, and click the Create Role Mapping button.
   The Role mapping confirmation message displays.

💡 You can no longer edit the values in the Login URL, Certificate (base 64), and XML signature key name fields.

3. Click the Confirm role mapping button or Cancel to return to the SAML Integration page in the Admin Console.

6. Test the integration using default roles

1. Click Open this link in private mode to test login in the SAML Integration page, next to the name of your new IdP.
   
   
2. Test the integration by logging in with a user account that is assigned the role, User.
   If the log in is successful, the Shows the mapped SAML claims window is displayed.

3. Repeat step 2 with user accounts that have the roles, Author and Admin.

7. Select the default identity provider

💡 Only set your new IdP as the default identity provider AFTER you have tested both role mapping and logging in. Failure to do this could mean that users in your organization cannot login into BRYTER. If this happens, contact support@bryter.io 

1. From the Select default identity provider dropdown at the top of the SAML Integration page, select the appropriate IdP.
   
   
2. Click the Change button.
   The IdP you have created and configured is now the default.