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.
A Google OAuth client app ID for OAuth-based authentication with Google (e.g., Google SSO with OIDC or using a Google Sheets resource).
CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
A Google OAuth client app secret for OAuth-based authentication with Google (e.g., Google SSO with OIDC or using a Google Sheets resource).
CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz
CUSTOM_LOGOUT_REDIRECT=https://example.com/logout/success
The lifespan, in minutes, of custom OpenID provider tokens.
Default value is 120
.
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES=60
An identifier for a resource to which users should have access upon completion of an OpenID authorization process.
CUSTOM_OAUTH2_SSO_AUDIENCE=https://retool.auth0.com/api/v2
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.
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups
The mapping of roles from your OpenID provider to Retool permission groups.
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.
CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED=true
The endpoint for Retool to make an additional request for a fat token containing all available claims from your OpenID SSO provider.
CUSTOM_OAUTH2_SSO_USERINFO_URL=https://yourcompany.okta.com/oauth2/v1/userinfo
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.
DEFAULT_GROUP_FOR_DOMAINS=example1.org -> admin, example2.com -> viewer
Disable username and password authentication. If true, users can only log in using SSO.
DISABLE_USER_PASS_LOGIN=true
INVITES_PER_DAY=100
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.
JWT_SECRET=676765765327645bvbfgbsfhfbgr
The organization's email domain in DC syntax when syncing Google Groups to Retool.
LDAP_BASE_DOMAIN_COMPONENTS=dc=example,dc=com
The mapping of Google LDAP Groups or SAML groups to Retool permission groups used for Google Group syncing and SAML role mapping.
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.
LDAP_ROLE_MAPPING_DISABLED=true
The certificate from the downloaded bundle when syncing Google Groups to Retool.
LDAP_SERVER_CERTIFICATE=filename
The private key from the downloaded bundle when syncing Google Groups to Retool.
LDAP_SERVER_KEY=filename
LDAP_SERVER_NAME=ldap.google.com
The LDAP server URL for Google's Secure LDAP Service when syncing Google Groups to Retool.
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.
LDAP_SYNC_ALL_GROUPS=true
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.
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN=true
Restrict users from logging in unless they use SSO for the specified domain. Specify comma-separated values for multiple domains.
RESTRICTED_DOMAIN=example.com,example.org
The first name attribute in the SAML response.
Default value is firstName
.
SAML_FIRST_NAME_ATTRIBUTE=nameFirst
SAML_GROUPS_ATTRIBUTE=userGroups
An XML document that contains information necessary for configuring SAML-enabled identity or service providers.
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>"
The last name attribute in the SAML response.
Default value is lastName
.
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.
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.
SCIM_AUTH_TOKEN=token
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.
SENDING_INVITES_WITH_EMAIL_DISABLED=true
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.
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=true
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.
TRIGGER_SAML_LOGIN_AUTOMATICALLY=true