Configure Okta OIDC SSO

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

Available on:
• Enterprise plan

To configure Okta OIDC SSO, you need:

• An Okta account with permissions to create an OIDC integration.
• The ability to set environment variables on self-hosted Retool instance, or admin permissions for Retool Cloud.

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.

Setting	Value
Sign-on method	OIDC - OpenID Connect
Application type	Web Application
Sign-in redirect URIs	https://YOUR_RETOOL_DOMAIN/oauth2sso/callback
Sign-out redirect URIs	https://YOUR_RETOOL_DOMAIN/api/logout

To add a Retool tile in Okta, set the TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY environment variable to true or enable Trigger login automatically on Settings > Single Sign-On (SSO). In Okta, use the following settings:

Setting	Value
Initiate login URI	YOUR_RETOOL_DOMAIN
Login initiated by	Either Okta or App
Login flow	Redirect to app to initiate login (OIDC Compliant)

2. Configure settings in Retool

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.

SSO settings

On Retool Cloud and self-hosted Retool versions 3.16 and later, enter settings on Settings > Single Sign-On (SSO). Depending on your setup, you might not need to configure all of these values. If you aren't sure where to find token and auth URLs, try using the /.well-known/openid-configuration endpoint.

Setting	Example
Client ID	CLIENT_ID
Client secret	CLIENT_SECRET
Scopes	openid email offline_access profile
Fat token URL	https://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/userinfo
Auth URL	https://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/authorize
Token URL	https://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/token
Email key	idToken.email
First name key	idToken.given_name
Last name key	idToken.family_name

After you save your settings, you can log in using Okta SSO. You can test out your configuration by logging in from an incognito window.

Environment variables

On self-hosted Retool versions earlier than 3.16, configure the following environment variables on your Retool instance.

Environment variable	Example
CUSTOM_OAUTH2_SSO_CLIENT_ID	CLIENT_ID
CUSTOM_OAUTH2_SSO_CLIENT_SECRET	CLIENT_SECRET
CUSTOM_OAUTH2_SSO_SCOPES	openid email offline_access profile
CUSTOM_OAUTH2_SSO_USERINFO_URL	https://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/userinfo
CUSTOM_OAUTH2_SSO_AUTH_URL	https://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/authorize
CUSTOM_OAUTH2_SSO_TOKEN_URL	https://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/token
CUSTOM_OAUTH2_SSO_JWT_EMAIL_KEY	idToken.email
CUSTOM_OAUTH2_SSO_JWT_FIRST_NAME_KEY	idToken.given_name
CUSTOM_OAUTH2_SSO_JWT_LAST_NAME_KEY	idToken.family_name

You can also configure an access token refresh time using the CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES environment variable.

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

BASE_DOMAIN=https://retool.yourcompany.com

After you restart your Retool instance, you can log in using Okta SSO. You can test out your configuration by logging in from an incognito window.

Role mapping with Okta Group Claims

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.

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 and name it groups.

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.

Custom claims

To send custom Okta attributes—for example, employee number or department—to Retool, you can configure custom claims in Okta.

1. Add attributes to the Retool profile from Profile editor > Add attributes, and from Profile editor > Mappings, map them to the correct fields.
2. Add claims to the authorization server. You may want to limit the scope of these claims.
3. To confirm your custom attributes were correctly added, you can preview a sample token from Security > API > Default > Preview in Okta.
4. When you next log in to Retool using SSO, you can view attributes in current_user.metadata.userInfoResponse.

3. Add additional settings

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.

SSO settings

On Retool Cloud and self-hosted Retool versions 3.16 and later, enter settings on Settings > Single Sign-on (SSO). Add the groups scope to the Scopes fields.

Specify the roles key—for example, idToken.groups—in the Roles key field.

Specify any additional remapping in the Role mapping field. For example, Retool devops->admin maps members of the "Retool devops" group to Retool admins.

Environment variables

On self-hosted Retool versions earlier than 3.16, use environment variables to configure additional settings.

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.

CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups

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

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.

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_ID_TOKEN as authentication in resources.