Configure Auth0 OIDC SSO

📘

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

Suppose we want to set up SSO with Auth0 for an instance of Retool running on https://retool.foocorp.com.

1. Obtain your Client ID and Client Secret

2. Find your OAuth Authorization URL and OAuth Token URL

3. Add Retool to your callback URL.

4. Get an example ID Token.

For example, with Auth0, ID Tokens look like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJnaXZlbl9uYW1lIjoiRm9vIiwiZmFtaWx5X25hbWUiOiJCYXIiLCJuaWNrbmFtZSI6ImZvb2JhciIsIm5hbWUiOiJGb28gQmFyIiwicGljdHVyZSI6Imh0dHBzOi8vZm9vLmJhciIsImxvY2FsZSI6ImVuIiwidXBkYXRlZF9hdCI6IjIwMjAtMDktMjVUMDY6NTk6MzAuMjA4WiIsImVtYWlsIjoiZm9vYmFyQGZvb2NvcnAuY29tIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsImlzcyI6Imh0dHBzOi8vcmV0b29sLmF1dGgwLmNvbS8iLCJzdWIiOiJnb29nbGUtb2F1dGgyfDExMTExMTExMTExMTExIiwiYXVkIjoiWW91ckNsaWVudElEIiwiaWF0IjoxNjAxMDE3MTcwLCJleHAiOjE2MDEzNTMxNzB9.15ZdZH2R06JuCcI_rDoz55h8QIh4xCQlQWAnWcf72hg

Which when decoded, look like this:

{
  "given_name": "Foo",
  "family_name": "Bar",
  "nickname": "foobar",
  "name": "Foo Bar",
  "picture": "https://foo.bar",
  "locale": "en",
  "updated_at": "2020-09-25T06:59:30.208Z",
  "email": "[email protected]",
  "email_verified": true,
  "iss": "https://retool.auth0.com/",
  "sub": "google-oauth2|11111111111111",
  "aud": "YourClientID",
  "iat": 1601017170,
  "exp": 1601353170
}

We see here that the email field is what we'll want to use to identify the user, and that the given_name and family_name correspond to the user's first and last name.

5. Take this information and translate them to environment variables for Retool:

Here's an example of how you might configure the Auth0 app:

CUSTOM_OAUTH2_SSO_CLIENT_ID = yypLZ44LxEz0XlQZBu5k2Nq9XsdOv4f5
CUSTOM_OAUTH2_SSO_CLIENT_SECRET = xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CUSTOM_OAUTH2_SSO_SCOPES = openid email profile offline_access
CUSTOM_OAUTH2_SSO_AUTH_URL = https://retool.auth0.com/authorize
CUSTOM_OAUTH2_SSO_TOKEN_URL = https://retool.auth0.com/oauth/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

6. (Optional) If you want to provide authorization to access resources when a user logs in with SSO, you need to specify the API audience that corresponds to the resource as configured in Auth0. Find the API audience in the Auth0 UI under Applications > APIs, and set it as the value of the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable in your Retool deployment. For example, CUSTOM_OAUTH2_SSO_AUDIENCE = https://retool.auth0.com/api/v2

🚧

If you don't configure the CUSTOM_OAUTH2_SSO_AUDIENCE environment variable, Retool receives an opaque token, and you won't be able to use the accessToken to control access to components and resources.

7. Restart your Retool container with the environment variables, and you should now have SSO set up.

8. (Optional) As an Admin, you can enable just-in-time (JIT) user provisioning under Organization settings -> Advanced if you do not wish to provision users manually.

9. (Optional) Set the environment variable TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=true if you would like users to automatically be prompted with the Oauth 2.0 authorization screen.