Configure Okta OIDC SSO

Learn how to set up Okta SSO using OpenID Connect (OIDC).


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


To configure Okta OIDC SSO, you need:

  • An Okta account with permissions to create an OIDC integration
  • The ability to set environment variables on your Retool instance

1. Create a new app integration

Follow the steps in Okta to create a new OIDC integration. Use the following settings, replacing YOUR_RETOOL_DOMAIN with your Retool instance.

Sign-on methodOIDC - OpenID Connect
Application typeWeb Application
redirect URIshttps://YOUR_RETOOL_DOMAIN/oauth2sso/callback
Sign-out redirect URIshttps://YOUR_RETOOL_DOMAIN/api/logout

2. Set environment variables on Retool

On your Retool instance, set the following environment variables. Replace with your Okta domain.

CUSTOM_OAUTH2_SSO_SCOPESopenid email offline_access profile

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.


After you restart your Retool instance, you can log in using Okta SSO.

Role mapping with Okta Group Claims

Use the following instructions to automatically map your Okta groups with Retool permission groups when a user logs in.

1. Create a new scope

Follow the instructions in Okta to create a new API access scope for your authorization server.

2. Create a new claim

Follow the instructions in Okta to create a new claim.

In the Add claim form, select ID Token and Always in the dropdown. In the Value type section, select Groups.

You can add an optional Filter to limit the groups to sync.

In the Scopes section, add in the API access scope you previously created.

3. Set environment variables

Add the groups scope to the CUSTOM_OAUTH2_SSO_SCOPES environment variable.

CUSTOM_OAUTH2_SSO_SCOPES=openid email profile offline_access groups

Specify that the groups can be read in the idToken.


Specify any additional remapping. The following example maps members of the "Retool devops" group to Retool admins.

CUSTOM_OAUTH2_SSO_ROLE_MAPPING=Retool devops -> admin

4. Test your login

Log in as another user to confirm your permissions were correctly updated automatically.

You can also now use USER_OAUTH2_ACCESS_TOKEN and USER_OAUTH2_ACCESS_ID as authentication in resources.