Leveraging Entra ID to authenticate users and map Azure roles to Torq roles enhances security and streamlines user management, all without the need for Auth0. This guide provides a step-by-step approach to setting up SSO with Entra ID, ensuring a secure and efficient login process for Torq users.
Important!
Before getting started, make sure you understand how to prevent user lockouts by reviewing this KB article.
Set Up App Registration in Entra
To begin, register a new app in your Azure portal to connect your Torq workspace with Entra ID:
Access Azure Portal: Log into your Azure portal and navigate to App Registrations, selecting New Registration to initiate a new app setup.
Configure App Details: Fill in the application registration form with the necessary details.
Name: Torq.io
Supported account types: Accounts in this organizational directory only.
Redirect URL (optional):
Platform: Web
Register and Note IDs: After clicking Register, note the Application (client) ID and Directory (tenant) ID for later use in Torq.
Adjust Authentication Settings: In the Authentication section, enable ID tokens by selecting them under the Implicit grant and hybrid flows.
Create Client Secret: Under Certificates & secrets, generate a new client secret, and click Add.
Name: torq
Description: A brief description of the secret.
Expires: 24 months or a custom date that is more than 24 months. After the secret expires, you won't be able to log in to Torq using the secret.
Secret value: Copy the secret value and save it in a secure location. You'll need this later to finish configuring SSO in Torq.
Update the Manifest: Go to the Manifest section to update the application by modifying its JSON representation.
Set the acceptMappedClaims key to true.
The Redirect URI above is the Login redirect URL provided by Torq. See section 2.
When using version 16.1 or newer of the Safari browser, you have to make sure the Login redirect URL in Torq is https://app.torq.io/__/auth/handler or EU: https://app.eu.torq.io/__/auth/handler. If this isn’t the case, you should contact your support representative and ask them to update this URL for your Torq workspace before you continue. If you already set up SSO for your Torq workspace, you have to update the Login redirect URL you provided to your IdP after the support representative updates the URL for your Torq workspace.
Contact Torq support if you need to change the Login redirect URL.
Define App Roles and Permissions
Create App Roles: Navigate to App roles and click Create app role. Add a new role for each Torq role you wish to mirror, ensuring you create mappings for roles like TorqViewer, TorqOperator, TorqContributor, and TorqOwner.
The name you enter in the Value field will be the value for the Claim Value field in Torq when you set up role mapping.
Assign Permissions: Ensure the User.Read permission is listed under API permissions and grant admin consent to finalize the setup.
Read more about privileged roles in Entra ID here.
To allow Entra to reset users' passwords, assign the User.ReadWrite.All application permission and at least a User Administrator Microsoft Entra role.
A recommended claim to add is last_name (source attribute: User.Surname) and first_name (source attribute: User.GivenName) to ensure user names are sent to Torq.
Configure SSO 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 OpenID Connect as the protocol and select Microsoft Entra ID 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 Entra ID, then click Next to define claims mappings (see below).
Field | Value |
Login Redirect URL | US: |
Client ID | Copied from Entra ID |
Client Secret | Copied from Entra ID |
Issuer URL |
|
Requested Scopes | Permissions your application requests from the identity provider |
Code flow | A secure, two-step process where an authorization code is exchanged for tokens on the server side |
Implicit flow | Tokens are returned directly in the browser |
Send login hint to SSO provider | Optionally sends the user’s email or username as a login hint to the SSO provider |
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.
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.
Assign App Roles to Users in Azure
Finally, assign the configured Azure roles to your users:
Locate Your App: Within Azure, search for Enterprise applications and select your Torq app.
Add Users to Roles: Click Users and groups > Add user/group, select the users to assign to each Torq role, and confirm the assignments.
Under Users, click None Selected.
Search for and click all the users to add to a specific role and click Select, and then Assign.
