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 will contain the email of the user being authenticated.
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.
Configure SSO for your provider
Follow the configuration guides to set up SSO with OIDC for Auth0, Google, Okta, or Azure AD.
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
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.
|Roles||Role mapping setting||Result|
|["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_ACCESS_ID is replaced with the ID token obtained in the auth flow.
If your OpenID Provider returned a
refresh tokenin 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
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.accessToken keys. Access them using curly braces anywhere in your Retool app:
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
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
During the authentication flow, Retool replaces the thin token with the fat token returned from this endpoint.
Updated 8 days ago