Configure SSO with OIDC authentication

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 will contain the email of the user being authenticated.

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 environment variables

To enable SSO with OIDC, you must set the following environment variables on your Retool instance.

CUSTOM_OAUTH2_SSO_CLIENT_ID=XXXXXXXXXX
CUSTOM_OAUTH2_SSO_CLIENT_SECRET=XXXXXXXXXX
CUSTOM_OAUTH2_SSO_SCOPES=openid email offline_access profile
CUSTOM_OAUTH2_SSO_AUTH_URL=https://yourcompany.idprovider.com/oauth2/v1/authorize
CUSTOM_OAUTH2_SSO_TOKEN_URL=https://yourcompany.idprovider.com/oauth2/v1/token
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY=idToken.email

You should also set the BASE_DOMAIN environment variable to ensure links using your domain—for example, new user invitations and forgotten password resets—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

Configure SSO for your provider

Follow the configuration guides to set up SSO with OIDC for Auth0, Google, Okta, or Azure AD.

Role mapping

You can use environment variables to 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.

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

CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups
CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer

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

Examples

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_ACCESS_ID is replaced with the ID token obtained in the auth flow.

📘

Refresh tokens

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. To add custom claims to Okta, for example, add attributes to the Retool profile, then add claims to the authorization server. In OneLogin, you add custom claims from the Parameters page.

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