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.
All properties for this object with supported data types or values. You can write JavaScript almost anywhere in Retool to manipulate or read property values.
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 | ||||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
abcdefghijklmnopqrstuvwxyz
CUSTOM_LOGOUT_REDIRECT
A URL that users are redirected to after logging out of Retool.
| Type | string | ||||
| Format | URL | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
idToken.groups
CUSTOM_OAUTH2_SSO_ROLE_MAPPING
The mapping of roles from your OpenID provider to Retool permission groups.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||||
| Mutability |
|
Examples
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 | ||||||
| Mutability |
|
Examples
true
INVITES_PER_DAY
The number of invites that can be sent to users.
| Type | number | ||||
| Mutability |
|
Examples
100
JIT_ENABLED
Whether to enable JIT user provisioning.
| Type | boolean | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
676765765327645bvbfgbsfhfbgr
LDAP_BASE_DOMAIN_COMPONENTS
The organization's email domain in DC syntax when syncing Google Groups to Retool.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
true
LDAP_SERVER_CERTIFICATE
The certificate from the downloaded bundle when syncing Google Groups to Retool.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
filename
LDAP_SERVER_KEY
The private key from the downloaded bundle when syncing Google Groups to Retool.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
filename
LDAP_SERVER_NAME
The LDAP server name when syncing Google Groups to Retool.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
true
LDAP_SYNC_GROUP_CLAIMS
Enable syncing Google Groups to Retool.
| Type | boolean | ||||
| Mutability |
|
Examples
true
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN
Prevent Retool from resetting your password when logging in with Google for the first time.
| Type | boolean | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
example.com,example.org
SAML_FIRST_NAME_ATTRIBUTE
The first name attribute in the SAML response.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
nameFirst
SAML_GROUPS_ATTRIBUTE
The groups attribute in the SAML response.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
userGroups
SAML_IDP_METADATA
An XML document that contains information necessary for configuring SAML-enabled identity or service providers.
| Type | string | ||||
| Format | Plain Text | ||||
| Mutability |
|
Examples
<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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
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 | ||||
| Mutability |
|
Examples
true