Configure Microsoft Entra ID OIDC SSO
Learn how to set up Microsoft Entra ID SSO with OpenID Connect (OIDC).
To configure SSO with Microsoft Entra ID OIDC, you must:
- Have permission to create an Microsoft Entra ID Enterprise application.
- Have admin permissions on your Retool instance. For self-hosted deployments, you must also have the ability to configure environment variables.
1. Create an Microsoft Entra ID Enterprise application
To create an Microsoft Entra ID Enterprise application, follow the steps in Azure's documentation.
-
In the Microsoft Entra ID portal, add a new Enterprise application.
-
Retool is not listed in the Microsoft Entra ID Gallery, so select Create your own application.
-
Name the application.
-
Select Register an application to integrate with Microsoft Entra ID (App you're developing).
-
Under Supported account types, select Accounts in this organizational directory only (Default Directory Only - Single tenant).
-
Under Redirect URI, select Web. Enter
https://retool.yourcompany.com/oauth2sso/callback
under the path, replacingretool.yourcompany.com
with your Retool instance domain. This specifies the path where Microsoft Entra ID redirects users after they complete authentication.
2. Configure secrets
-
In the settings for the new Retool enterprise application, select the Single sign-on menu. Select the App registrations experience.
-
Select the Certifications & secrets menu. Add a new client secret and set an expiration period. You must update your Retool deployment when the secret expires, so you should set the maximum allowable period to 24 months.
-
Save this secret for use in a later step.
3. Configure claims
-
In the Azure app registration experience, select the Token configuration menu.
-
Select Add optional claim for the ID token. At a minimum, add the following claims:
acct
email
family_name
given_name
-
When you save the claims, turn on the Microsoft Graph email, profile permissions.
-
Optionally, specify additional claims to include for the Access token.
4. Configure optional group claims
You can optionally map Microsoft Entra ID groups to Retool groups to automatically assign users to groups when they authenticate using SSO. This requires adding group claims to the ID token.
-
In the Azure app registration experience, select the Token configuration menu.
-
Select Add optional claim for the ID token.
- In the claim, include the groups you want to map to Retool groups.
- Include the Group ID for ID, Access, and SAML.
5. Retrieve connection details
-
In the Azure app registration experience, select the Overview menu and select Endpoints.
-
Save the following fields:
- Application (client) ID
- OAuth 2.0 authorization endpoint (v2)
- OAuth 2.0 token endpoint (v2)
6. Configure settings in Retool
Configure your Microsoft Entra ID settings in Retool.
When possible, use the Settings UI to configure SSO for a more streamlined setup. Existing environment variables pre-populate in the Settings UI, which you can override or preserve. Some settings are only available as environment variables.
- SSO settings page
- Environment variables
On Retool Cloud and self-hosted Retool versions 3.16 and later, enter settings on Settings > Single Sign-On (SSO).
Setting | Example |
---|---|
Client ID | CLIENT_ID |
Client secret | CLIENT_SECRET |
Scopes | openid profile email offline_access |
Auth URL | https://login.microsoftonline.com/<issuer>/oauth2/v2.0/authorize |
Token URL | https://login.microsoftonline.com/<issuer>/oauth2/v2.0/token |
Email key | idToken.email |
User info URL (Fat token URL) | https://yourcompany.idprovider.com/oauth2/v1/userinfo |
For Microsoft Entra ID OIDC, leave User info URL (Fat token URL) unset.
On self-hosted Retool versions earlier than 3.16, add the following environment variables to your Retool instance. Be sure to include the BASE_DOMAIN
environment variable so links using your domain are correct. Retool's backend tries to determine the BASE_DOMAIN
if it is not set, but it can be incorrect if your website uses a proxy.
Environment variable | Example |
---|---|
CUSTOM_OAUTH2_SSO_CLIENT_ID | CLIENT_ID |
CUSTOM_OAUTH2_SSO_CLIENT_SECRET | CLIENT_SECRET |
CUSTOM_OAUTH2_SSO_SCOPES | openid profile email offline_access |
CUSTOM_OAUTH2_SSO_AUTH_URL | https://login.microsoftonline.com/<issuer>/oauth2/v2.0/authorize |
CUSTOM_OAUTH2_SSO_TOKEN_URL | https://login.microsoftonline.com/<issuer>/oauth2/v2.0/token |
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY | idToken.email |
CUSTOM_OAUTH2_SSO_USERINFO_URL | https://yourcompany.idprovider.com/oauth2/v1/userinfo |
BASE_DOMAIN | https://retool.yourcompany.com |
See thin tokens and fat tokens for more detail on the User Info URL or CUSTOM_OAUTH2_SSO_USERINFO_URL
environment variable.
Optional settings
To pass the user's first name and last name to Retool, set the following settings.
- SSO settings page
- Environment variables
Setting | Example |
---|---|
First name key | idToken.given_name |
Last name key | idToken.family_name |
Role mapping modify group memberships on subsequent logins. During initial configuration, test role mapping on a non-admin user or verify that a separate admin can log in with an alternate authentication method to avoid losing admin access.
If you configured group claims, construct a role mapping string to map Microsoft Entra ID group object IDs to Retool group names. Find Microsoft Entra ID group object IDs in the Azure Groups application.
For example, given an Microsoft Entra ID group called Retool Editors
with an object ID of fd951-f454-4b7a
, use the mapping string fd951-f454-4b7a -> editor
to assign its members to the Editor group in Retool.
To add role mapping, set the following environment variables in your Retool instance.
Setting | Example |
---|---|
Roles key | idToken.groups |
Role mapping | fd951-f454-4b7a -> editor |
Environment variable | Example |
---|---|
CUSTOM_OAUTH2_SSO_JWT_FIRST_NAME_KEY | idToken.given_name |
CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEY | idToken.family_name |
If you configured group claims, construct a role mapping string to map Microsoft Entra ID group object IDs to Retool group names. Find Microsoft Entra ID group object IDs in the Azure Groups application.
For example, given an Microsoft Entra ID group called Retool Editors
with an object ID of fd951-f454-4b7a
, use the mapping string fd951-f454-4b7a -> editor
to assign its members to the Editor group in Retool.
To add role mapping, set the following environment variables in your Retool instance.
Environment variable | Example |
---|---|
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY | idToken.groups |
CUSTOM_OAUTH2_SSO_ROLE_MAPPING | fd951-f454-4b7a -> editor |
7. Test SSO
-
Navigate to the
/auth/login
page for your Retool instance. -
Click the Sign in with SSO button.
Retool redirects you to login.microsoft.com
, where you are prompted for credentials. After entering credentials for a user assigned to the Retool app in Azure, you are redirected back to Retool and logged into the instance. In the Retool App IDE, confirm that an idToken
and accessToken
are available as keys on the current_user.metadata
object.