Configure Azure AD OIDC SSO

📘

SSO with Azure AD OIDC is only available for organizations on the Enterprise plan running self-hosted Retool.

Requirements

To configure SSO with Azure Active Directory OIDC, you must:

• Have permission to create an Azure Active Directory Enterprise application.
• Have the ability to configure environment variables on your Retool instance.

1. Create an Azure AD Enterprise application

To create an Azure AD Enterprise application, follow the steps in Azure's documentation.

1. In the Azure Active Directory portal, add a new Enterprise application.

2. Retool is not listed in the Azure AD Gallery, so select Create your own application.

3. Name the application.

4. Select Register an application to integrate with Azure AD (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 Azure AD 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

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

4. Optionally, specify additional claims to include for the Access token.

4. Configure optional group claims

You can optionally map Azure AD 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. Set Retool environment variables

In your Retool instance, set the following environment variables.

You should also set the BASE_DOMAIN environment variable to ensure links using your domain are correct. Retool's backend tries to guess BASE_DOMAIN if it is not set, but it can be incorrect if your website uses a proxy.

BASE_DOMAIN=https://retool.yourcompany.com

7. Set optional Retool environment variables

To pass the user's first name and last name to Retool, set the following environment variables in your Retool instance.

If you configured group claims, construct a role mapping string to map Azure AD group object IDs to Retool group names. Find Azure AD group object IDs in the Azure Groups application.

For example, given an Azure AD 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.

8. Enable JIT user provisioning

Enabling JIT user provisioning is optional, but recommended.

Just in time (JIT) user provisioning enables Retool to provision user accounts when users sign in for the first time. This means you don't need to manually invite each user to Retool. To enable JIT user provisioning, toggle on the Enable JIT user provisioning setting on the Settings > Advanced page.

9. Test SSO

1. Navigate to the /auth/login page for your Retool instance.

2. 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 editor, confirm that an idToken and accessToken are available as keys on the current_user.metadata object.