Please note that this is a premium feature that needs to be enabled by your dedicated customer success manager. For further information, please reach out to your BRYTER Customer Success Manager or firstname.lastname@example.org. Additional pricing may apply.
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).
What is a SAML integration?
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 also means user creation and assigning roles is not possible anymore in BRYTER but needs to be done by the administrators of your identity provider.
❗ Please note that this article assumes that you are familiar with setting up a SAML Integration. If you have no knowledge about this please contact the responsible technical administrator in your organization to assist you in the set up process.
💡 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)
Setting up SAML
First select "SAML Integration" in the Admin Console.
Create Identity provider
Add a new identity provider by click on "New Identity Provider" on the right side.
❗ Note that you cannot change the identifier later.
Configure Identity provider
As a new step you need to download the SAML Service Provider metadata file (thethat we provide). This contains the necessary information so that you can create the SAML Identity Provider metadata file (the that you need to provide) with your identity provider.
It is recommended to import the SAML Service Provider metadata.xml in your identity provider directly. If you need to configure your identity provider manually the following attributes are important:
- Entity ID: Identitfier for the identity provider. This is currently fixed for the tenant (will not change when creating a new identity provider configuration)
- X509Certificate (for signing): Certificate needed for signing of the login request
- AssertionConsumerService / SingleLogoutService Binding: Method that is used to login/logout. Need to be set to
- AssertionConsumerService / SingleLogoutService Location: URL where login/logout request is sent
- Name-ID format: Specifies to format how a user is identified. Needs to be set to
After you have obtained the SAML Identity Provider metadata file from your identity provider, the following information is required:
- Login URL: Usually this information is in the tag in the metadata file
- Certificate (Base64): This needs to be the X.509 certificate for signing (not for encryption). Usually this information is in the ) or footer tag as a children of the tag in the metadata file. Do not include header (
- XML signature key name: Depends on your identity provider. Usually is used by Microsoft AD FS, is used by Keycloak and other Red Hat based identity provider other might work with the option
- Logout URL: Optional, usually this information is in the tag in the metadata file First name claim / Last name claim / Email claim (attributes mapping): Mapping for first name, last name and email field. Usually the default claims don't need to change.
Note that if you have already created users in BRYTER the email claim should match with the existing addresses so that any existing data by users is kept.
After all these information is provided you need to check if the login and the attributes mapping works. Open "Open this link in private mode to test login" in private mode and check if the login works.
If the login doesn't work, check the Login URL, Certificate (Base64) and XML signature key name. If you can login check if the informations provided on the SSO Check page are correct. Note that no role is mapped yet.
If you see this account update page instead at least one of the attributes (first name, last name, email) is not mapped correctly. Do not fill out but instead check your identity provider configuration and try again until the mapping is successful.
Configure role mapping
After you have verified the login, you can create the role mapping by click on "Role Mapping"
Usually you shouldn't need to change the the defaults and can just select the 'Create Role Mapping' button:
Note that you cannot change the Login URL, Certificate (Base64) and XML signature key name after you created the role mapping.
As a final verification step, your admins need to check if the role mapping is working for all roles (, , and ). This requires three different users in your identity provider and can be checked via "Open this link in private mode to test login".
Use Identity Provider as default login
Once the role mapping configuration is completed, you can select your identity provider as the default login method for your BRYTER tenant.
❗ Note that you should only do this after testing that the login and the role mapping work. Otherwise, users in your organization might not be able to login into BRYTER. If this happens, contact email@example.com.
Incomplete vs. complete configuration
If your configuration is incomplete, for example due to missing role mapping, you cannot activate SAML successfully. This will be visually highlighted in yellow.
Only completed configurations will be displayed with a green background color.