License requirements:
SAML SSO is only supported on the Deployment Enterprise and Data Backup Enterprise tiers.
Note: SAML user accounts are new, distinct accounts and cannot be linked to old accounts e.g. Google, Salesforce. Org connections, jobs and other settings will need to be recreated on these accounts.
This article is specific to Okta, we have more general documentation which can be applied to other providers as well.
We are going to switch between the Okta Admin page and Gearset Single sign on page all through this document.
Go to Okta Admin page - Applications - Create App Integration
Click on SAML 2.0
In the Create SAML Integration page you can provide the App name - For example Gearset.
Click Next. Then configure SAML settings.
Single Sign-on URL - Switch to Gearset settings page and Copy
Assertion Consumer Service (ACS) URLAudience URI (SP Entity ID) - Copy the
Entity IDfrom Gearset settings page.
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).
The following OKTA fields, make sure that your SAML settings are the same as shown below:
SAML 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.
If you click on Learn More - and search for SAML issue ID from their documentation, you can copy this value which we have to fill in the Gearset page at a later stage. As the time of writing all ID's seem to be http://www.okta.com/${org.externalKey}.
For the additional attributes, copy the attribute identifier shown in Gearset into your IdP and configure the value of the attribute appropriately.
In this example the email and display name for users are being set as attributes.
For display name I am typing in the value:
user.firstName + user.lastName
You can preview the SAML assertion generated from the information here. Click Next.
Depending upon your company setting fill in these details as needed on the next page.
Settings in Gearset
Go to Gearset - My account - Single Sign on page
Create a SAML ID for your team.
New User creation options: Here you can select if you want users to add to your team automatically when they sign up.
Issuer ID: Next step is to fill in
Issuer IDwhich you can get as mentioned in the steps here. This is called SAML Issuer ID in Okta.Identity Provider Single sign-on URL: In OKTA, this is found in General → App Embed Link. Copy and paste this into Gearset.
Scroll down to the bottom to find the
Embed Linkand copy and paste to Gearset.
Active Signing Certificate: Navigate to Sign On page in Okta and scroll to the bottom.
You may need to Update Application Username, so press Update now. After this, you’ll see SAML signing Certificates. Generate a new certificate.
Generate New certificate and click on Actions - View IdP metadata
This will take you through to a XML file, carefully copy the string of letters and numbers into the Active Signing Certificate box making sure no other characters are entered during the process.
Paste these in Gearset and click on Save configuration.
Activate Gearset app
Next step is to make the app active. Follow these steps for the same.
In OKTA, you need to go to the Assignments tab of the newly created app and assign the App to a person (you) and make sure the App is active.
Now click on My end user dashboard and verify the newly created App is showing.
You can click on the app and verify it takes you to Gearset and depending upon the configuration you have put here in Sign On page of Okta, you will be redirected straight to Gearset or will ask for a password or authenticator access.
Using the original Gearset login, assign the Okta Gearset account a license and assign as a Team owner. Then log back into the Okta Gearset account.
It can be helpful to remove any licenses and team owner status from the original account and remove it from the team.
Add users to Okta for Gearset access.
The next step is to add users to Okta so that they can see the Gearset app in their Okta login.
Once a colleague joins the team, a team owner can assign licenses and change team role as desired.
In Gearset - go to Team management - your team's name - add the licenses to the users who have joined/setup the account using SSO.
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.