Single sign-on

The Single Sign-On feature allows you to integrate a third party Identity Provider and enable single sign-on (SSO). SSO allows a user to authenticate once with your IdP and then access Synerise or other enabled Service Providers, without the necessity to authenticate with each of those applications separately.

Synerise provides Security Assertion Markup Language (SAML) based single sign-on where you can integrate with any Identity Provider (IdP) that uses SAML 2.0 protocol, which is a widely-accepted standard for exchanging authentication and authorization data between Synerise and Identity Providers such as Microsoft Azure, Google Workspaces, Okta, and more.

Understanding SAML-based SSO

In order to understand how SAML-based single sign-on works, take a look at the diagram below.

Step 1. As a user, you attempt to access app.synerise.com (Service Provider) that normally requires login credentials to access it. Assuming you have configured SAML for your profile, it leads you to the Identity Provider (Step 2).

Step 2. Based on the provided user ID (e-mail), the Service Provider redirects the user to Identity Provider’s SSO Endpoint with a SAML authentication request (that has been built based on the configuration set for your Identity Provider in app.synerise.com).

Step 3. Identity Provider validates SAML authentication request received from the Service Provider and presents a user with the IdP’s login form (please note that it may be a password-less authentication for some identity providers, like for example Microsoft Azure)

Step 4. The Identity Provider generates a SAML response.

Step 5. The SAML response is passed from the user’s browser to the Service Provider’s redirect URI.

Step 6. The Service Provider validates the authenticity and integrity of the response and upon success, it issues access token/cookie, and as a result, the user is signed in to app.synerise.com

Benefits

• Centralized user management - With the identity provider, you get to administer users from one central place in your organization.

• Increased security - The benefit of a single user account in many applications helps to maintain a single identity and credentials, so users don’t have to remember too many credentials. Authentication takes place only with the identity provider, with a single set of security-related policies regardless of the application.

• Improved user experience - Your users only need to sign in once to use multiple applications. This approach ensures faster authentication, saves time and relieves users from remembering multiple credentials.

Good practices

• Remember to have a strong password policy, two-factor authentication, and other security policies configured with your Identity Provider as the ones available in Synerise won’t apply to regular users.

• Configure password requirements or two-factor authentication for your workspace in Synerise, as it will be enforced for the Guest accounts (users that are not managed by you).

Prerequisites

• You must be granted user permissions to access Settings and configure Identity provider.
• You must verify the ownership of at least one domain (could be more if needed).
• Create a backup user that won’t be using the same email address in the Identity Provider account. This is not required if you start with the Allow signing in with both methods authentication mode (explained here).
• You must have access to Identity Provider’s admin panel to configure SAML application.

Configuration parameters explanation

Configuration parameter	Description
General settings
Authentication mode	There are three option to choose from: - Allow signing in with in-built account only - It allows to sign in only users who have account in Synerise (logging in with an email address and password). - Allow signing in with Identity provider account only - It allows to sign in only those users who have account in the service of the identity provider. It disables signing in with the Synerise credentials and enforces authentication through your Identity Provider credentials and enforce authentication through your Identity Provider. - Allow signing in with both methods - It allows to sign in through two methods simultaneously: either with Synerise credentials or through Identity provider account. In the beginning when you’re testing the identity provider authorization, we recommend to enable two options of authorization.
Sign-in button label	The text in this field is displayed on the button to your users.
Authentication settings
Managed domains	In this field, select the domains (used in the user's accounts) for which the identity provider authorization is available. The list includes only verified domains (learn how to verify a domain). This option is available only to the verified domains for the security reasons.
Use Attribute containing email address instead of Subject	Identity provider is required to pass the identity attribute of a user who wants to log in to Synerise. This identity attribute is an email address. Each identity provider chooses their own way of passing this attribute. If the identity provider passes a user's email address in other attribute than `subject`, enable this option.
Identity provider email attribute	Available when the **Use Attribute containing email address instead of Subject** toggle is switched on. Enter the URL of the email attribute. You can find information where to find it in the identity provider's documentation. An exemplary attribute which contains an email address, returned in an authorization response from the identity provider: <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”> <AttributeValue>john.doe@example.org</AttributeValue>
Just-in-Time Provisioning
Update user roles on sign-in	Configure the method of updating user permissions (it's useful in situations when user permissions are modified between log-ins both in Synerise and Identity Provider portal): - Full sync - This setting allows you to always enforce user roles based on group or role claims from SAML response provided by your Identity Provider. Whenever a user authenticates, Synerise overwrites the permissions with the ones sent by the IdP. Consider that as 'replace'. - Add missing - When this option is selected, user roles will only be added to the ones that are missing for a user's account, but it won't modify any extra roles that you might have added directly in Synerise. - No - If you choose this option, authentication response won't overwrite user roles and they can only be assigned/modified directly in Synerise
Unsuspend users	This option unblocks users (who blocked themselves by entering a wrong password several times, for example) after the authorization through identity provider. It's particularly useful for Allow signing in with both methods authentication mode.
Dynamic role assignment	You can set different user roles for various user groups from the identity provider service. To do so, you must enter the URL of the group attribute, then enter the ID of the group and select a user role. The opposite method is the static role assignment (see next table row), which involves assigning the same user role for everyone authorizing through an identity provider.
Roles	It must be filled in if, when the Dynamic role assignment is disabled. Select a user role assigned to every user who authorizes through an identity provider.
SAML protocol settings
Identity provider Entity ID	You can find it in the identity provider's portal or documentation. Expected value type: URL.
SSO endpoint (https)	You can find it in the identity provider's portal or documentation. It may be the same as in Identity provider Entity ID. Expected value type: URL.
Identity provider application ID	You can find it in the identity provider's portal. Expected value type: string.
Service provider redirect URI	This field is always filled in by default. It's useful while registering the Synerise application in your identity provider service.
Request Signature	To increase security, you can require a SAML signature for authorization requests by enabling this option.
Request binding	Define how the requestors and responders communicate by exchanging messages.
Request signature algorithm	Select the key Synerise uses to sign the request. Currently unused.
Response signature verification	You can define where the SAML signature is available.
Response signature algorithm	Define the algorithm the identity provider used to sign the response. This field is not required because Synerise receives the identity provider certificate that contains the response key used by the identity provider.
IdP signature certificate	Upload the file that contains the identity provider certificate which is used to validate the response. It's available either in the identity provider's portal or in their documentation.
Max clock skew	Define the acceptable time of discrepancy between issuing the authorization by the identity provider and receving it by Synerise.

Make log-in screen modifications

1. Go to Settings > Access Control > Identity Providers.
2. To define the available login methods and the text on the button:
   1. From the Authentication mode dropdown list, select one of the available modes:
      • Allow signing in with in-built account only - Users can only log in with an email address and password.
      • Allow signing in with Identity Provider account only - User can only log in through the identity provider.
      • Allow signing in with both methods - Users can log in with those two methods.
   2. In the Sign-in button label field, enter the text that is displayed on the button in the Synerise log-in window for the identity provider authentication method.

Define authentication settings

1. To define the domains for which this authentication method is enabled and how the email attribute is passed to Synerise, in the Authentication settings section:
   1. In the Managed domains field, select verified domains for which this authentication method is available.
      
      Important: If you want to include all verified domains, you must select them all in the field - domain verification itself does not automatically enable this method of authentication.
   2. If the identity provider passes a user’s email address in other attribute than subject, switch the Use Attribute containing email address instead of Subject toggle on.
      Result: An IdP email attribute field appears.
   3. In the IdP email attribute field, enter the URL of the email attribute.
      Tip: You can find it in the XML file generated while registrating Synerise application in your identity provider portal or you can find it in the identity provider documentation.

Define permissions for users who authorize by identity provider

1. To defined a user’s permissions when they authenticate, in the Just-in-Time provisioning section:
   1. From the Update user roles on sign-in dropdown list, select the method of updating user roles (it’s useful in situations when user permissions are modified between log-ins both in Synerise and Identity Provider portal):
      Tip: Explanation of every option is available here.
      • Full sync
      • Add missing
      • No
   2. To enable unblocking Synerise users by Identity Provider authorization, switch the Unsuspend users toggle on.
      Result: If a user is blocked in Synerise, the Identity Provider authorization unblocks this user.
   3. Define how you want to assign user permissions for users authorizing by Identity Provider:
      Static role assignment

      To enable static role assignment (every user receives the same user permissions), from the Role dropdown list, select a Synerise user role.

      Dynamic role assignment

      1. To enable dynamic assignment of user permissions through SAML mapping, switch the Dynamic role assignment toggle on.
         Result: Three text fields appear.
         1. In the SAML Attribute name field, enter the URL of the identity provider’s group attribute.
            Tip: You can find it in the identity provider portal or you can find it in the identity provider documentation.
         2. In the SAML Attribute value field, enter the value of the attribute.
            Tip: You can find it in the identity provider portal or you can find it in the identity provider documentation.
         3. From the Role dropdown, select a user role for the attribute.
         4. To add more attributes and assign roles to them, click Add and repeat steps I-III.

Adjust SAML protocol settings

1. To set up SAML-based single sign-on, the identity provider and service provider must establish trust with each other. To do this, in the SAML protocol settings section:
   1. In the Identity provider Entity ID field, enter the URL (you can find it in the Identity provider’s portal or in their documentation).
   2. In the SSO endpoint (https) and Identity provider application ID fields, provide data from the Identity provider portal.
      
      Tip: You can refer to the Identity provider’s documentation.
   3. The Service provider redirect URI field is filled in by default.
   4. From the Request binding dropdown list, select one method of exchanging authentication:
      • HTTP POST
      • HTTP REDIRECT
   5. To sign a request with SAML certificate, switch the toggle Request signature on (recommended).
   6. Omit the Request signature algorithm, Response signature verification, and Response signature algorithm fields.
   7. To add a certificate, you must:
      1. Open the XML file received during registering the Synerise app in Identity provider’s portal.
      2. Copy the certificate path.
      3. Paste it into a new file.
      4. Save the file.
      5. Upload the file to the IdP Signature Certificate field.
   8. To define the maximum and acceptable time discrepancy between issuing authorization and receiving it in Synerise, in the Max Clock Skew, define the time period.
2. Confirm by clicking Apply.

Test SSO

After completing the setup, test the integration.

1. If you are logged in to Synerise, log out.
2. Go here.
3. Enter your email address.
4. Click Continue.
5. Click the Sign in with Provider’s name (the text on the button depends on the value you entered in the Sign-in button label field.
   Result: You will be redirected to your Identity Provider’s service where you will be authenticated immediately if there is an active session or you will be asked to authenticate and as a result you’ll be redirected back to Synerise.

Congratulation! You signed in through your Identity Provider.