Configure Single Sign-On

  • Updated
Follow

Audience

Integrating BRYTER with your organization’s SSO technologies requires a range of skills:

  • systems administrators with responsibility for administering user access and authentication via SSO
  • strategic planners with responsibility for evaluating and planning secure authentication services

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.

This article assumes that you are familiar with setting up an SSO Integrations. If you have no knowledge of this process, please contact your technical administrator for assistance.

SSO integration products

BRYTER, as a service provider, can integrate with each of the identity provider products listed here. We’ve provided a link to their identity provider setup documentation.

These technologies are currently not supported (please contact us if you require them):

  • SCIM
  • OpenID

 

Before you begin …

  • The configuration requires two metadata.xml files:
      • Service Provider (SP) metadata, that you download from the BRYTER Single sign-on page; and
      • Identity Provider (IdP) metadata that you download from your IdP.

Data from each of these files is combined to enable communication between the client, the SP, and the IdP.

  • The method used to log in/log out must be set to HTTP-Post.
  • If you have existing BRYTER user accounts and want to retain the data associated with those accounts, be sure to create an exact match between the user account email addresses and the email claims. If these email addresses do not match, 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 will need three different user accounts: one with the role User, one Author, and one Admin.

 

Where to begin — the Single sign-on page

You can create a new IdP, edit an existing integration, or check a configuration, in the Single sign-on page in the Admin Console. Selecting any of the intuitively-titled links or buttons will take you to further pages to add or edit configuration data.Bildschirmfoto 2022-06-23 um 07.44.57.png

The Single sign on page is the location of all the functionality you will need to create and configure SAML.

 

Single sign-on configuration process

Integrating BRYTER with an IdP requires some initial configuration in your IdP and the creation of a new IdP configuration in the BRYTER Single sign-on page in the Admin Console.

1. In BRYTER

  1. Create a new IdP configuration
  2. Download the BRYTER metadata.xml file

2. In your IdP

  • You must create a new app in your IdP — BRYTER does not provider one.
  • Encryption and Single Log Out are not supported.
  1. Create a new service provider configuration in your IdP.

Be sure to add roles equivalent to those you will set up in BRYTER.

  1. Download the metadata.xml file from your IdP’s configuration.

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

3. In BRYTER

  1. Configure the newly-created IdP configuration.

This configuration will require some of the values in the downloaded IdP metadata.xml file.

  1. Test authentication between the IdP and the SP.
  2. Configure role mapping.
  3. Test logging in to Bryter.
  4. Enable the new IdP.

 

Configure single sign-on for a new IdP in BRYTER

Complete these steps to configure single sign on for your organization.

1. Create a new IdP configuration

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

  1. Select Single sign-on in the BRYTER Admin Console.
  2. Select the New identity provider button.

    The New identity provider pop up displays.

  1. Enter a value into the Name field.
  2. Click the Create identity provider button.

    The Single sign on page displays the new IdP configuration.

2. Download the BRYTER metadata.xml file

Select the Download metadata.xml link, displayed alongside the new IdP name. The file will contain this default information:

Parameter

Information type

Comment
Entity ID The unique identifier of the entity This is currently fixed for the tenant and will not change when creating a new IdP configuration.
X509Certificate (for signing) Required for signing login requests  
AssertionConsumerService / SingleLogoutService Binding Method used to log in/log out. Must be set to HTTP-Post  
Name-ID format Specifies a standard format for user ids. Set to Persistent

The value must be exactly urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.

   

3. Configure the newly-created IdP configuration

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

  1. Select Edit, next to the name of your new IdP
  2. Enter appropriate values into these fields:app.bryter.io_admin_saml_edit.png
Name  
Login URL This information is usually found in the SingleSignOnService tag in the IdP 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.
External Id claim (optional)  

3. Select the Update identity provider button

4. Test authentication between the IdP and the SP

  1. In the Single Sign-On page, next to the name of your new IdP, right-click Open this link in private mode to test login and open the link in incognito/private mode.

    You will be prompted to log in.

If you simply select Open this link in private mode to test login, the claims of the user account currently logged in will be displayed.

  1. Log in using the user account whose claims you want to preview.

    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 to amend the values.

  1. If you can not log in successfully, check:
    • the Login URL, Certificate (base 64) and XML signature key name in the IdP configuration; and
    • that all email claims are correct.

        Do not forget — no role is mapped yet, you are simply testing authentication.

5. Configure role mapping

    BRYTER currently supports three user classifications: User, Author, and Admin.

    Ensure that the names of roles match those in the IdP configuration.

  1. In the Single Sign-On page, next to the name of your new IdP configuration, select Role Mapping.
  2. If required, edit the the default values, Admin and Author, then select 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.

  1. Select the Confirm role mapping button or Cancel to return to the Single sign-on page in the Admin Console.

6. Test logging in to BRYTER

  1. Select Open this link in private mode to test login next to the name of your new IdP in the Single sign on page.

    You are now testing both authentication via the IdP and user role access to BRYTER.

  1. Log 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.

If the Shows the mapped SAML claims window is not displayed, check that the role mapping in your IdP configuration matches the configuration here. Our SAML Troubleshooting guide provides further assistance.

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

7. Enable the new IdP

💡 Only set your new IdP as the default identity provider AFTER you have tested: authentication — logging in before assigning roles; and access to BRYTER — after assigning different roles to user accounts. 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 Single sign on page, select the appropriate IdP name.
  2. Select the Change button.

    The IdP you created and configured is now the default IdP for BRYTER.

 

 

 

 

 

Related articles