To configure SSO using Okta as the IdP and SAML 2.0 as the authentication and authorization protocol, you need to perform several steps in Torq and several in Okta.
Before you continue, try configuring SSO using the Torq application from the Okta app catalog as that's the process we recommend.
Important!
Before getting started, make sure you understand how to prevent user lockouts by reviewing this KB article.
Create a new SSO provider in Torq
Sign in to Torq as an Owner to perform the following steps.
Access SSO Settings: Go to Settings > Security > Configure SSO.
Select Protocol and Identity Provider: In the IdP Selection section, choose SAML 2.0 as the protocol and select Okta as your Identity Provider.
Click Next to continue.
Enter IdP Setup Details: In the IdP Setup section, fill in the following fields with the values obtained from Okta, then click Next.
Field | Value |
Audience Restriction |
|
Login Redirect URL | US: |
Sign-On URL | Copied from Okta |
Issuer URL | Copied from Okta |
Public Certificate | Copied from Okta |
When using Safari v16.1 or newer, the Login Redirect URL must be:
https://app.torq.io/__/auth/handler
If this value differs, contact Torq Support to update the URL for your workspace before continuing.
Create a new SAML 2.0 Application in Okta
1. Log in to Okta as an administrator.
2. Go to the Applications section and click Create App Integration.
3. Select the Sign-in method to be SAML 2.0.
4. The app name should be set to Torq.
5. Select the Do not display application icon to users option. IdP-initiated flows with SAML 2.0 aren't currently supported.
Configure the New Application Settings
Configure the SAML 2.0 protocol settings.
1. Single sign-on URL: Login Redirect URL copied from the IdP Connection form in Torq in a previous step.
2. Audience URI: torq.io (same value as the Audience Restriction field in the IdP Connection form in Torq).
3. Name ID format: EmailAddress.
4. Application username: Email.
5. Update application username on: Create and update.
6. Add the required attribute mapping:
user.firstName is mapped to first_name.
user.lastName is mapped to last_name.
7. In the Group Attribute Statements section, modify the filter to contain groups Matches regex .*. The filter value is case-sensitive, so groups must be lowercase.
Complete the SSO setup in Torq
For this step, you'll need to enter some information from Okta in the corresponding SSO fields in Torq.
1. Once the new app is created in Okta, go to the Sign On tab and click View Setup Instructions.
2. In Torq, go to Settings > SSO Login.
3. In the IdP Connection section, click Add and enterthe values from Okta to the corresponding fields.
Identity Provider Single Sign-On URL to Sign-On URL.
Identity Provider Issuer to Issuer URL.
Certificate to Public Certificate.
Assign the application to Relevant Users/Groups
In the Assignments section, select the users and groups to assign the application.
Define SSO Claims Mapping
The Claims Mapping determines which Torq role is assigned to each user based on identity provider attributes.
Add Claim Mapping Rules: In the Claims Mapping section, click Add Claim to create a new rule.
The wizard automatically offers the first mapping,
email, marked as recommended.This field is auto-filled with the email address of the current user (the Owner performing the setup).
You can optionally edit this initial mapping before saving.
After editing, click Add to move the mapping into the saved section.
Provide Mapping Details: For each rule, define the following:
Claim Name: The field from your IdP (for example,
emailorgroups).Claim Value: The expected value of the claim (case-sensitive).
Assigned Role: The Torq role to assign (for example, Admin, Editor, Viewer).
Organize Claim Priority:
Mappings are evaluated top-down.
Place the claim with the highest privilege role at the top.
Lower-privilege mappings should follow in descending order.
A user’s role is determined by the first matching claim.
Save Configuration: After defining all required mappings, click Save to complete the setup.
Important!
The first email claim mapping is essential to prevent account lockouts in Torq. Do not delete it until SSO has been tested and verified with other users, as any misconfiguration in Torq or your IdP could result in loss of access.
