Skip to main content

Configure Okta OIDC SSO

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

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.

SettingValue
Sign-on methodOIDC - OpenID Connect
Application typeWeb Application
Sign-in redirect URIshttps://YOUR_RETOOL_DOMAIN/oauth2sso/callback
Sign-out redirect URIshttps://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:

SettingValue
Initiate login URIYOUR_RETOOL_DOMAIN
Login initiated byEither Okta or App
Login flowRedirect 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.

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.

SettingExample
Client IDCLIENT_ID
Client secretCLIENT_SECRET
Scopesopenid email offline_access profile
Fat token URLhttps://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/userinfo
Auth URLhttps://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/authorize
Token URLhttps://yourcompany.okta.com/oauth2/YOUR_AUTH_SERVER_NAME/v1/token
Email keyidToken.email
First name keyidToken.given_name
Last name keyidToken.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.

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.

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.

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

3. Test the connection​

Once you've configured your settings, click Save Changes. To test the integration and its settings, click the Test Connection button.

This triggers a simulation of the SSO flow that ensures that the proper groups are mapped, the right user metadata is sent from your identity provider, and the integration works seamlessly. Clicking the Test Connection button does not change the current user's permission groups, and you won't be locked out if SSO is misconfigured.

After Retool tests the connection, a new tab opens and displays the Connection Status, Issues Detected, and Connection Details. If there are any issues, this page displays warnings and recommendations to resolve them. You can see the full response from the SSO provider in the Connection Details section.

Once you are satisfied with your configuration, log out of Retool and log back in using SSO to test the flow yourself.

If you use a self-hosted deployment and updated your environment variables, restart your Retool instance.