Skip to main content

Configure Microsoft Entra ID OIDC SSO

Learn how to set up Microsoft Entra ID SSO with OpenID Connect (OIDC).

Available on:Enterprise plan

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.

  1. In the Microsoft Entra ID portal, add a new Enterprise application.

  2. Retool is not listed in the Microsoft Entra ID Gallery, so select Create your own application.

  3. Name the application.

  4. Select Register an application to integrate with Microsoft Entra ID (App you're developing).

  5. Under Supported account types, select Accounts in this organizational directory only (Default Directory Only - Single tenant).

  6. Under Redirect URI, select Web. Enter https://retool.yourcompany.com/oauth2sso/callback under the path, replacing retool.yourcompany.com with your Retool instance domain. This specifies the path where Microsoft Entra ID redirects users after they complete authentication.

2. Configure secrets​

  1. In the settings for the new Retool enterprise application, select the Single sign-on menu. Select the App registrations experience.

  2. 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.

  3. Save this secret for use in a later step.

3. Configure claims​

  1. In the Azure app registration experience, select the Token configuration menu.

  2. Select Add optional claim for the ID token. At a minimum, add the following claims:

  • acct
  • email
  • family_name
  • given_name

  1. When you save the claims, turn on the Microsoft Graph email, profile permissions.

  2. 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.

  1. In the Azure app registration experience, select the Token configuration menu.

  2. 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​

  1. In the Azure app registration experience, select the Overview menu and select Endpoints.

  2. 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.

On Retool Cloud and self-hosted Retool versions 3.16 and later, enter settings on Settings > Single Sign-On (SSO).

SettingExample
Client IDCLIENT_ID
Client secretCLIENT_SECRET
Scopesopenid profile email offline_access
Auth URLhttps://login.microsoftonline.com/<issuer>/oauth2/v2.0/authorize
Token URLhttps://login.microsoftonline.com/<issuer>/oauth2/v2.0/token
Email keyidToken.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.

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.

SettingExample
First name keyidToken.given_name
Last name keyidToken.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.

SettingExample
Roles keyidToken.groups
Role mappingfd951-f454-4b7a -> editor

7. Test the connection​

Once you've configured your settings, click Save Changes. To test the integration and its settings, click the Test Connection button.

This triggers a simulation of the SSO flow that ensures that the proper groups are mapped, the right user metadata is sent from your identity provider, and the integration works seamlessly. Clicking the Test Connection button does not change the current user's permission groups, and you won't be locked out if SSO is misconfigured.

After Retool tests the connection, a new tab opens and displays the Connection Status, Issues Detected, and Connection Details. If there are any issues, this page displays warnings and recommendations to resolve them. You can see the full response from the SSO provider in the Connection Details section.

Once you are satisfied with your configuration, log out of Retool and log back in using SSO to test the flow yourself.

If you use a self-hosted deployment and updated your environment variables, restart your Retool instance.