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.
Requirements
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.
| 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 |
2. Set environment variables on Retool
On your Retool instance, set the following environment variables. Replace https://yourcompany.okta.com with your Okta domain.
| Setting | 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/v1/userinfo |
CUSTOM_OAUTH2_SSO_AUTH_URL | https://yourcompany.okta.com/oauth2/v1/authorize |
CUSTOM_OAUTH2_SSO_TOKEN_URL | https://yourcompany.okta.com/oauth2/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 |
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES | 720 |
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.
BASE_DOMAIN=https://retool.yourcompany.com
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.
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
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.
Updated 20 days ago