SSO environment variables
SSO-related environment variables for self-hosted deployments.
Authentication environment variables available for use with Self-hosted Retool deployments.
Only configure environment variables when needed. You can configure many environment variables from your organization's Settings rather than directly editing your deployment's configuration file.
You must restart your instance after setting any variables for them to take effect.
CLIENT_ID
A Google OAuth client app ID for OAuth-based authentication with Google (e.g., Google SSO with OIDC or using a Google Sheets resource).
| Type | string |
| Format | Plain Text |
| Configurability | Settings > SSO > Client ID > Client IDUpdate the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
CLIENT_SECRET
A Google OAuth client app secret for OAuth-based authentication with Google (e.g., Google SSO with OIDC or using a Google Sheets resource).
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz
CUSTOM_LOGOUT_REDIRECT
A URL that users are redirected to after logging out of Retool.
| Type | string |
| Format | URL |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CUSTOM_LOGOUT_REDIRECT=https://example.com/logout/success
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES
The lifespan, in minutes, of custom OpenID provider tokens.
| Type | number |
| Format | Integer |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | 120 |
Examples
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES=60
CUSTOM_OAUTH2_SSO_AUDIENCE
An identifier for a resource to which users should have access upon completion of an OpenID authorization process.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CUSTOM_OAUTH2_SSO_AUDIENCE=https://retool.auth0.com/api/v2
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY
Returns an array of strings where each string represents an OpenID group name. This setting is used with CUSTOM_OAUTH2_SSO_ROLE_MAPPING to map groups to Retool permission groups.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups
CUSTOM_OAUTH2_SSO_ROLE_MAPPING
The mapping of roles from your OpenID provider to Retool permission groups.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer
CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED
Disables the mapping of roles from your OpenID provider to Retool permission groups. Set this variable to true to disable passing roles from JWTs.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED=true
CUSTOM_OAUTH2_SSO_USERINFO_URL
The endpoint for Retool to make an additional request for a fat token containing all available claims from your OpenID SSO provider.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
CUSTOM_OAUTH2_SSO_USERINFO_URL=https://yourcompany.okta.com/oauth2/v1/userinfo
DEFAULT_GROUP_FOR_DOMAINS
The default Retool user group for a Google SSO domain. Default groups only apply to new users who sign up using SSO, not existing users signing in.
| Type | string |
| Format | Plain Text |
| Configurability | Settings > SSO > Google SSO > Default Group for DomainsUpdate the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
DEFAULT_GROUP_FOR_DOMAINS=example1.org -> admin, example2.com -> viewer
DISABLE_USER_PASS_LOGIN
Disable username and password authentication. If true, users can only log in using SSO.
| Type | boolean |
| Format | True/False |
| Configurability | Settings > SSO > Disable Login with Email and PasswordUpdate the deployment's configuration file. |
| Required | Optional |
| Default | false |
Examples
DISABLE_USER_PASS_LOGIN=true
INVITES_PER_DAY
The number of invites that can be sent to users.
| Type | number |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | 50 |
Examples
INVITES_PER_DAY=100
JIT_ENABLED
Whether to enable JIT user provisioning.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | false |
Examples
JIT_ENABLED=true
JWT_SECRET
The JWT secret token to sign requests for authentication with Retool's backend API server. If changed, all active user login sessions are invalidated.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
JWT_SECRET=676765765327645bvbfgbsfhfbgr
LDAP_BASE_DOMAIN_COMPONENTS
The organization's email domain in DC syntax when syncing Google Groups to Retool.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
LDAP_BASE_DOMAIN_COMPONENTS=dc=example,dc=com
LDAP_ROLE_MAPPING
The mapping of Google LDAP Groups or SAML groups to Retool permission groups used for Google Group syncing and SAML role mapping.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
LDAP_ROLE_MAPPING=retool-admins -> admin, support -> Support
LDAP_ROLE_MAPPING_DISABLED
Disable syncing SAML groups or Google Groups to Retool permission groups. When LDAP_ROLE_MAPPING is set and LDAP_ROLE_MAPPING_DISABLED is true, Retool logs the groups that would have synced to Retool when a user logs in.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | false |
Examples
LDAP_ROLE_MAPPING_DISABLED=true
LDAP_SERVER_CERTIFICATE
The certificate from the downloaded bundle when syncing Google Groups to Retool.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
LDAP_SERVER_CERTIFICATE=filename
LDAP_SERVER_KEY
The private key from the downloaded bundle when syncing Google Groups to Retool.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
LDAP_SERVER_KEY=filename
LDAP_SERVER_NAME
The LDAP server name when syncing Google Groups to Retool.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
LDAP_SERVER_NAME=ldap.google.com
LDAP_SERVER_URL
The LDAP server URL for Google's Secure LDAP Service when syncing Google Groups to Retool.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
LDAP_SERVER_URL=ldaps://ldap.google.com:636
LDAP_SYNC_ALL_GROUPS
Whether to sync all groups regardless of whether they're configured in the LDAP_ROLE_MAPPING environment variable. When enabled, new groups are created during SAML sync.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | false |
Examples
LDAP_SYNC_ALL_GROUPS=true
LDAP_SYNC_GROUP_CLAIMS
Enable syncing Google Groups to Retool.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | false |
Examples
LDAP_SYNC_GROUP_CLAIMS=true
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN
Prevent Retool from resetting your password when logging in with Google for the first time.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN=true
RESTRICTED_DOMAIN
Restrict users from logging in unless they use SSO for the specified domain. Specify comma-separated values for multiple domains.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
RESTRICTED_DOMAIN=example.com,example.org
SAML_FIRST_NAME_ATTRIBUTE
The first name attribute in the SAML response.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | firstName |
Examples
SAML_FIRST_NAME_ATTRIBUTE=nameFirst
SAML_GROUPS_ATTRIBUTE
The groups attribute in the SAML response.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | groups |
Examples
SAML_GROUPS_ATTRIBUTE=userGroups
SAML_IDP_METADATA
An XML document that contains information necessary for configuring SAML-enabled identity or service providers.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
SAML_IDP_METADATA=<md:EntityDescriptor xmlns:md="urn:desert:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/your_entity_id"><md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:desert:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>your_certificate</ds:X509Certificate></ds:X509Data></ds:KeyInfo></md:KeyDescriptor><md:NameIDFormat>urn:desert:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat><md:SingleSignOnService Binding="urn:desert:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://example-98123.okta.com/app/company/jfdu90324f/sso/saml"/><md:SingleSignOnService Binding="urn:desert:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://example-98123.okta.com/app/company/your_entity_id/sso/saml"/></md:IDPSSODescriptor></md:EntityDescriptor>"
SAML_LAST_NAME_ATTRIBUTE
The last name attribute in the SAML response.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | lastName |
Examples
SAML_LAST_NAME_ATTRIBUTE=nameLast
SAML_SYNC_GROUP_CLAIMS
Sync Retool group memberships using the retool- prefix with the groups listed in SAML_GROUPS_ATTRIBUTE. The prefix is not shown in the Retool interface.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
SAML_SYNC_GROUP_CLAIMS=true
SCIM_AUTH_TOKEN
A secret token shared with your SSO provider to provision user accounts. If you use Spaces, this token only applies to the admin Space.
| Type | string |
| Format | Plain Text |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
SCIM_AUTH_TOKEN=api-key
SENDING_INVITES_WITH_EMAIL_DISABLED
Allow user invites without pinging Retool's user invitation server. You must enable this if you have an airgapped deployment.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
SENDING_INVITES_WITH_EMAIL_DISABLED=true
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY
Automatically start the Oauth 2 SSO login flow when users navigate to your Retool instance. Use either TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY or TRIGGER_SAML_LOGIN_AUTOMATICALLY, you cannot enable both.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=true
TRIGGER_SAML_LOGIN_AUTOMATICALLY
Automatically start the SAML SSO login flow when users navigate to your Retool instance. Use either TRIGGER_SAML_LOGIN_AUTOMATICALLY or TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY, you cannot enable both.
| Type | boolean |
| Configurability | Update the deployment's configuration file. |
| Required | Optional |
| Default | null |
Examples
TRIGGER_SAML_LOGIN_AUTOMATICALLY=true