Skip to main content

Configure SSO with OIDC authentication

Learn how to configure SSO with OpenID Connect (OIDC).

Retool's OpenID integration uses the Authorization Code Flow. Retool, at minimum, expects either an ID token or access token to be a JSON Web Token (JWT) that contains the email of the authenticated user.

Requirements​

To configure SSO with OIDC, you need:

  • The OAuth client ID for your application
  • The OAuth client secret for your application
  • A list of scopes to grant to Retool
  • The authorization endpoint for your OpenID provider
  • The token endpoint for your OpenID provider

You should confirm how your SSO provider formats its ID and access tokens. Retool attempts to decode these tokens as JWTs. You must provide Retool the path in the decoded JWT that corresponds with your identifying user information.

Some SSO providers don't return both an ID token and access token by default. You might need to provide additional metadata to obtain both tokens. See the provider-specific guides and generic process to obtain a fat token for more details.

Required settings​

Configure your SSO 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 value
Client IDXXXXXXXXXX
Client secretXXXXXXXXXX
Scopesopenid email offline_access profile
Auth URLhttps://yourcompany.idprovider.com/oauth2/v1/authorize
Token URLhttps://yourcompany.idprovider.com/oauth2/v1/token
Email keyidToken.email

Configure SSO for your provider​

Follow the configuration guides to set up SSO with OIDC for Auth0, Google, Okta, or Microsoft Entra ID.

Role mapping​

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.

You can also map the roles returned from the OpenID response to your Retool permission groups. Any Retool groups that are not specified in the role mapping are overwritten. Groups are created automatically in Retool when a user logs in.

The following example maps the devops and support roles to specific Retool permission groups.

SettingEnvironment variableExample value
Roles keyCUSTOM_OAUTH2_SSO_JWT_ROLES_KEYidToken.groups
Role mappingCUSTOM_OAUTH2_SSO_ROLE_MAPPINGdevops -> admin, support -> viewer

After setting these environment variables, a user's groups sync the next time they log in to Retool over SSO.

Roles set using this environment variable are case sensitive. This means:

  1. Roles set within your IdP that you pass within the variable need to match exactly. For example, if you have a Retool Admin role in your IdP, you need to pass Retool Admin.
  2. Roles within Retool are always lowercase. For example, if you have a Retool Admin role within your IdP, and you want to map it to Retool's admin role, you need to set it using Retool Admin → admin.

To disable role mapping, set CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED to true.

Examples​

RolesRole mapping settingResult
["admin", "editor"]""The user is added to the "admin", "editor", and "All Users" groups.
[]""The user is added to the "All Users" group.
["admin", "support"]""A new custom group called "support" is created.

The user is added to the "admin", "support", and "All Users" groups.
["support", "devops"]"devops -> editor"A new custom group called "support" is created.

The user is added to the "editor", "support", and "All Users" groups.

Use authentication JWTs in resources​

Using SSO with OIDC, you can reuse the tokens obtained throughout the SSO process in API calls you make from Retool to your backend services.

In the following example, USER_OAUTH2_ACCESS_TOKEN is replaced with the access token obtained in the auth flow, and USER_OAUTH2_ID_TOKEN is replaced with the ID token obtained in the auth flow.

Example using OAuth JWTs in resources

If your OpenID Provider returned a refresh token in the initial login flow, Retool automatically uses it to refresh the access and ID tokens every two hours by default. You can set a custom refresh time using the CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES environment variable.

Reference JWT claims in Retool apps​

You can use JWT claims returned by your SSO provider to personalize Retool apps or control component permissions. Retool automatically includes these claims as the values of the current_user.metadata.idToken and current_user.metadata.accessToken keys. Access them using curly braces anywhere in your Retool app: {{current_user.metadata.idToken.picture}}

Custom claims​

You can add custom claims following instructions from your IdP. See the guides to your IdP for instructions on where to add these claims. In Retool, custom claims are accessible in current_user.metadata.

Thin tokens and fat tokens​

Some OIDC identity providers, such as Okta, don't send all the claims associated with a user during the authentication flow. This is called a thin token and is used in place of a fat token, which returns all claims, for performance reasons. If your ID token is missing certain claims, you can tell Retool to make an additional request to a given endpoint for the fat token.

You can configure this endpoint in Settings > Custom SSO > Fat token URL on Retool Cloud, or using the CUSTOM_OAUTH2_SSO_USERINFO_URL environment variable on self-hosted deployments. For example, Okta uses the /userinfo endpoint.

CUSTOM_OAUTH2_SSO_USERINFO_URL=https://your-company.okta.com/oauth2/v1/userinfo

During the authentication flow, Retool replaces the thin token with the fat token returned from this endpoint.