Skip to main content
BRYTER Academy

Configure Single Sign-On (SSO)

Updated
This article builds upon the insights shared in SAML-Based Single Sign-On (SSO) Basics.

This article assumes that you are familiar with setting up SSO Integrations. For more details refer to the section on the intended audience. If you have no knowledge of this process, please contact your technical administrator for assistance.

Information on the intended 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
This is a licensed feature which can be enabled by your BRYTER contact person. For further information, please reach out to them or support@bryter.io. Additional pricing may apply.
Information on 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
You can also assign access rights in BRYTER based on groups defined in the Identity Provider. Learn more here.

Before you begin …

Preparations for SSO configuration
  • 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.

 

How to update an expired certificate

The certificate from your identity provider will expire at some point.

To add a new certificate

  • Acess the BRYTER Admin Console and navigate to the Single Sign-on section.
  • Click on Edit in the row with your identity provider.
  • Then, select Add new certificate.
  • Finally, enter your new certificate.

You can remove the old certificate if the new one is already active. Or you can remove it later and keep both for the migration period.

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.

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.

When setting up single sign-on for your organization using this documentation, you can choose either the basic or the detailed instruction based on your specific needs:

 

 

Single sign-on configuration process (Basic)

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.
  2. Test authentication between the IdP and the SP.
  3. Configure role mapping.
  4. Test logging in to BRYTER.
  5. Enable the new IdP.

 

 

Single sign-on configuration process (Detailed step-by-step)

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:

Detailed information on the metadata.xml file

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 It is also mentioned as "reply URL" in some IDPs. Please refer to the following tag in the XML file 
AssertionConsumerService
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:

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 user accounts in your IdP interface; or
  • not enable role mapping and manage user accounts in the Admin Console in BRYTER.

BRYTER currently supports three user classifications: End 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 the 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.

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

 

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.

Was this article helpful?

2 out of 4 found this helpful
Return to top

Related articles