License requirements:
SAML SSO is only supported on the Deployment Enterprise and Data Backup Enterprise tiers.
This article is specific to Okta, we have more general documentation which can be applied to other providers as well.
🛑 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.
Prerequisites
You must have Administrator access to your Okta Organization and Team Owner access to your Gearset team to be configure Okta SSO login with Gearset.
Step 1: Get Configuration Details from Gearset
First, we need to gather some specific URLs from Gearset to plug into Okta.
Log in to Gearset and navigate to My Account -> Single Sign-On.
Under the Gearset Information section, look for the following two values and keep this tab open (or copy them to a note):
Entity ID
Assertion Consumer Service (ACS) URL
Step 2: Create the App Integration in Okta
Log in to your Okta Admin Dashboard.
Go to Applications -> Applications.
Click Create App Integration.
Select SAML 2.0 and click Next.
General Settings:
App name: Enter
Gearset.App logo: (Optional) Upload a Gearset logo for easy recognition.
Click Next.
Configure SAML:
Paste the values you retrieved from Gearset in Step 1:
Single Sign On URL: Paste the ACS URL from Gearset.
Audience URI (SP Entity ID): Paste the Entity ID from Gearset.
Check the option
Use this for Recipient URL and Destination URL
Name ID format: Select
EmailAddress.Application username: Select
Okta username.
Name ID format and Application username are extremely important, they must produce a static identifier otherwise Gearset will detect the user as a new user on every login.
By default Okta sends the value of Application username as the Name ID.
We recommend using EmailAddress as your Name ID format and Okta username as your Application username. This allows for primary email addresses to be updated without impacting the Gearset user mapping.
If your organization does not use email format for your Okta usernames, then you MUST choose a more suitable option for your organization that will create a static identifier.
Advanced Settings
Click on Show Advanced Settings, and use the same settings as below
Gearset does not currently support Encrypted Assertions
Step 3: Configure Attribute Statements (in Okta)
Gearset requires specific user details to create the account. Scroll down to the Attribute Statements section in Okta and add the following mappings exactly as shown:
Name | Name Format | Value |
Basic | user.email | |
urn:gearset:display_name | Unspecified | user.firstName + user.lastName |
Step 4: Complete Application Configuration
Click Next.
Select
I'm an Okta customer adding an internal app.Check
This is an internal app that we have created.Click Finish.
Step 5: Get Configuration Details from Okta
Now that the app is created, you need to copy the details from Okta back into Gearset.
On the Sign On tab of your new Gearset application in Okta
Locate the SAML Signing Certificates section and click Download.
Step 6: Finalize Configuration in Gearset
Return to Single Sign-On in Gearset.
Log in to Gearset and navigate to My Account -> Single Sign-On
SAML ID: Create a unique team ID (e.g.,
yourcompany-gearset). This will be part of your custom login URL.
Issuer ID: Paste the Issuer from the Okta Sign on tab obtained in Step 5.
Identity Provider Single sign-on URL: Paste the Sign on URL from the Okta Sign on tab obtained in Step 5.
Active Signing Certificate: Open the downloaded certificate in a text editor and copy the full contents (including the
-----BEGIN CERTIFICATE-----and-----END CERTIFICATE-----lines).
Click Save configuration.
Step 7: Assign users to the new Gearset SAML application in Okta
In Okta select the newly created Gearset SAML app and make sure the App is set to Active (depending on your org settings this may need to be manually set to active).
Next go to the Assignments tab of the Gearset app and assign it to the desired users (including yourself).
Test Login:
Open an Incognito/Private window.
Go to the Gearset login page.
Click SAML Login.
Enter the friendly SAML ID you created in Step 6.
You should be redirected to Okta, and upon success, logged into a new Gearset account.
Note: Currently Gearset only supports Just in Time User provisioning i.e. If a user tries to log into Gearset and their account does not exist we will create one for them.
We do not currently support any type of Role/Permission provisioning.
Step 8: Adding SAML Users to Gearset
If the SAML users are new to Gearset (i.e. they do not have a Gearset account) they can be added to your team in two ways:
The user can log into Okta and click on the Gearset tile, this will do Just in Time provisioning and create a Gearset account for the user. A Team Owner will need to manually assign a license to the user in Gearset once their account has been created.
In Gearset - go to Team management - add the licenses to the users who have joined/setup the account using SSO.
A Team owner can use the team invite feature and send an invite link out to the required Users. By default this will automatically assign a license to the user when they create an account and log in. If you have disabled this option then you will then need to manually assign a license to the user.
If a SAML user already has an existing Gearset account then the only way to get them onto your team is to get a Team Owner to issue a team invite to the user.
Hopefully this will enable you to configure SAML SSO using Okta and connect to Gearset. If there are any questions, you can contact us through our In-app chat.