License requirements:

SAML SSO is only supported on the Deployment Enterprise and Data Backup Enterprise tiers.

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.

🛑 Critical Considerations Before You Begin

1. New Accounts are Created: SAML user accounts are new, distinct accounts. They cannot be linked to your existing login methods (e.g., Google, Salesforce). This means existing connections, jobs, and settings will not transfer and will need to be recreated.

2. Prevent Admin Lockout: You must ensure that at least one Team Owner maintains a non-SAML login method. This acts as a failsafe to prevent the entire team from being locked out of administrative settings if the SAML integration fails.

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.

Prerequisites

You must have Administrator access to your IdP and Team Owner access to your Gearset team to be configure SAML SSO login with Gearset.

Configuration

This document is a general guide, but we do have specific documents for OKTA, OneLogin and Microsoft Entra ID, if you're using one of those providers.

Configuration involves creating an application connection in your IdP, copying information from Gearset into the IdP and copying information from your IdP into Gearset.

First set up a new SAML 2.0 application within your given IdP. You can use one of our guides linked above to assist with this or refer to your IdP documentation on how to set up a new SAML 2.0 application.

While setting up your SAML 2.0 application you will need the Entity ID and the Assertion Consumer Service (ACS) URL from your Gearset team. In Gearset navigate to My Account -> Single sign-on.

Unfortunately, the names and locations of where Entity ID and where Assertion Consumer Service (ACS) URL are used vary from IdP to IdP. Please refer to your IdPs documentation to discern the correct field mappings.

As an example using Okta, here are the mappings from the values in Gearset (on the left) to the Okta SAML configuration (on the right):

Entity ID maps to Oktas Audience URI (SP Entity ID) field.
Assertion Consumer Service (ACS) URL maps to Oktas Single sign-on URL field.

There are settings that can be configured in your IdP that Gearset will use when first creating an account:

Name ID (normally configured separately)
Additional attributes
- User's email address
- User's display name

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).

For the additional attributes, copy the attribute identifier shown in Gearset (on the left) 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.

Configuration items set in Gearset:

In Gearset navigate to My Account -> Single sign-on.

Here you will be required to set up the following configuration items:

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 behaviour 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 IdP, 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 SAML IdP.
Active Signing Certificate - This is the certificate your SAML IdP uses to sign its messages. Gearset will use this to confirm the message and the provider's authenticity. Include both the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.

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.

If the SAML account being used is a service account with no access to email then the team owner will need to reach out to our support team directly to finalize the verification process for the account. This can be done through our in-app chat.

Logging in directly with a Login URL (SP initiated login)

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 (SP initiated login)

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 (IdP initiated login)

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, in Gearset 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.