This document is general, but we do have specific documents for OKTA and Microsoft Entra ID, if you're using one of those providers.
Security Assertion Markup Language (SAML) allows teams to connect their external Identity Provider (IdP) to Gearset so that they can use the same single sign-on (SSO) used to access other services to log into Gearset.
Once configured, Gearset will redirect a user to an external IdP for authentication. If successful, the IdP redirects back to Gearset with a set of assertions about the user e.g. email, display name etc.
Note: SAML SSO is only supported on the Deployment Enterprise and Data Backup Enterprise tiers. SAML user accounts are new, distinct accounts and cannot be linked to old accounts e.g. Google, Salesforce. Connections, jobs and other settings will need to be recreated.
Configuration
To configure SAML SSO you must be a team owner and have permission to administer your identity provider (e.g. Okta). Configuration involves creating an application connection in your IdP, copying information from Gearset into the IdP and copying information from your IdP into Gearset.
To configure, navigate to My Account -> Single sign-on.
Configuration items set in Gearset:
SAML ID - This ID will be used by your team to sign in to Gearset using SAML and must be unique. We recommend choosing something memorable for your team. It must only contain alphanumeric and hyphen characters.
New user creation options - Users who sign in with your SAML configuration will be automatically provisioned and added to your team. This default behavior can be switched off so users can log in but not automatically be added to the team (and will need to be invited).
Issuer ID - A unique identifier given by your SAML identity provider, we use this to determine which identity provider is responsible for the user's authentication.
Identity Provider Single sign-on URL - The URL that Gearset will use to log into your identity provider. This is provided by your IdP.
Active Signing Certificate - This is the certificate your SAML identity provider uses to sign its messages. Gearset will use this to confirm the message and the provider's authenticity.
A series of essential and optional configuration items are copied from Gearset and entered into your IdP. Essential items are:
Entity ID - Used to identity Gearset to your IdP.
Assertion Consumer Service (ACS) URL - This is the URL your IdP will use to redirect back to Gearset after authentication.
Unfortunately, the names and locations of these can vary from IdP to IdP. Using Okta as an example, here is the mapping from the value in Gearset (on the left) to the Okta SAML configuration (on the right):
The optional items relate to the information provided by your IdP after successful authentication. The IdP returns assertions to Gearset to identify the user. Name ID is the most important and is configured in the IdP. It must be configured to use a unique value for each user and cannot change (or the user will appear as a different user).
There are additional attributes which can be configured in your IdP that Gearset will use when first creating an account:
User's email address
User's display name
User's mobile phone number
User's timezone
For the additional attributes, copy the attribute identifier shown in Gearset into your IdP and configure the value of the attribute appropriately. In this Okta configuration example I am sending the email and display name for users as attributes.
Once configured, users can log into Gearset via SAML SSO.
Email verification
When attempting to log in to Gearset for the first time with a new SAML user account, or if the SAML user's email address changes, Gearset will require that the user verifies the email address that has been supplied by the identity provider.
An email will be sent to that address and the user will be required to click on the verification link prior to being able to log in. A message will be displayed to the user in Gearset informing them that they should check their email inbox.
This is a one time action for each user account, unless the email address for that user is changed within the identity provider.
Logging in directly with a Login URL
When the SAML ID has been defined, the SAML configuration screen will show a unique login URL for your team which you can distribute.
Following this link will allow Gearset to navigate you directly to your SSO for authentication and then back to Gearset, skipping the normal Gearset login screen.
Logging in via SAML from the login page
On the Gearset login screen, select the SAML login button and enter the SAML ID that was specified during SAML configuration. You will be redirected to your IdP and once successfully authenticated redirected and logged into Gearset.
After logging in successfully via SAML the next time you arrive at the Gearset login page, a shortcut button to your SAML configuration will be shown.
Logging in from your Identity Provider
Logging in from Gearset (either via the Login URL or the login page) is called service provider initiated SSO. You can also log in directly from your identity provider and this is called identity provider initiated SSO. The details of this are specific to each IdP but typically users will be presented with a dashboard of the applications they are allowed to use. For example, in Okta this may look like:
Your IdP administrator will configure this.
Editing the configuration
A SAML configuration can be edited, even to the point of completely changing your identity provider. As long as the Name ID remains the same the users will resolve to the same user.
To edit an existing configuration, navigate to My Account -> Single sign-on and scroll to the bottom and select Edit Configuration. Once your edits are complete, click on Save configuration.
Updating the active certificate
For security reasons it is beneficial to change the signing certificate periodically (e.g. every year). To update, edit the configuration as above and then enter the new certificate.
A new certificate is pending and the previous certificate will still be valid until a user logs in with the new certificate.
Note: We now accept SAML requests signed using either Canonicalization Method (http://www.w3.org/2001/10/xml-exc-c14n# or http://www.w3.org/2001/10/xml-exc-c14n#WithComments).