Skip to main content

Configure single sign-on (SSO)

  • Updated

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.
  • When you upload certificates, BRYTER will automatically locate all certificates. However, you can only add two manually in the Edit identity provider screen.
  • The certificate with the most recent expiry date will display in the Certificate Expiration Date field on the Single Sign-On screen. If two certificates are uploaded, the second certificate will automatically activate when the first expires — there will be no interruption to service for authors and users. The date of expired certificates is displayed in red.Expiry date.png

Where to begin — the Single sign-on page

You can create a new IdP, edit an existing integration, check a configuration or the expiry date of certificates, 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 a new or edit existing configuration data. Screenshot 2022-08-10 at 10-37-46 BRYTER Admin.png

The next step

The Edit identity provider page provides detail about the selected IdP and the ability to change the configuration and add new certificates.

Edit identity provider.png

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. The Edit identity provider screen displays.
  2. Enter appropriate values into the configuration fields:Screenshot 2022-08-10 at 10-37-01 BRYTER Admin.png

3. Select the Update identity provider button.

💡 If you need to edit the Name or Login URL of this configuration, return to this page, edit the values, and click 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

Role mapping is optional — you can choose to:

  • enable role mapping and administer all BRYTER roles in your identity provider interface; or
  • not enable role mapping and manage user accounts in the Admin Console in BRYTER.

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

Follow this procedure to enable role mapping — ensure that the names of the roles here are an exact match those in the IdP configuration.

  1. In the Single Sign-On page, next to the name of your new IdP configuration, click Edit. The Edit Identity Provider page displays.

  2. Click the Advanced Settings tab. The Role claims page displays.

  3. Enter values into the Admin and Author fields, then click the Update role mapping button. Any user who is granted access to BRYTER will have the role User by default if none other is specified.

    The Role mapping confirmation message displays. An error displays if the values are invalid.

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

  4. Click the Confirm role mapping button or Cancel to return to the Single sign-on page.

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