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