Skip to main content

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.

string

A Google OAuth client app ID for OAuth-based authentication with Google (e.g., Google SSO with OIDC or using a Google Sheets resource).

Example
CLIENT_ID=123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
string

A Google OAuth client app secret for OAuth-based authentication with Google (e.g., Google SSO with OIDC or using a Google Sheets resource).

Example
CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz
string

A URL that users are redirected to after logging out of Retool.

Example
CUSTOM_LOGOUT_REDIRECT=https://example.com/logout/success
number

The lifespan, in minutes, of custom OpenID provider tokens.

Default value is 120.

Example
CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES=60
string

An identifier for a resource to which users should have access upon completion of an OpenID authorization process.

Example
CUSTOM_OAUTH2_SSO_AUDIENCE=https://retool.auth0.com/api/v2
string

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.

Example
CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY=idToken.groups
string

The mapping of roles from your OpenID provider to Retool permission groups.

Example
CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer

CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED​

boolean

Disables the mapping of roles from your OpenID provider to Retool permission groups. Set this variable to true to disable passing roles from JWTs.

Example
CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED=true
string

The endpoint for Retool to make an additional request for a fat token containing all available claims from your OpenID SSO provider.

Example
CUSTOM_OAUTH2_SSO_USERINFO_URL=https://yourcompany.okta.com/oauth2/v1/userinfo
string

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.

Example
DEFAULT_GROUP_FOR_DOMAINS=example1.org -> admin, example2.com -> viewer
boolean

Disable username and password authentication. If true, users can only log in using SSO.

Example
DISABLE_USER_PASS_LOGIN=true

INVITES_PER_DAY​

number

The number of invites that can be sent to users.

Default value is 50.

Example
INVITES_PER_DAY=100

JWT_SECRET​

string

The JWT secret token to sign requests for authentication with Retool's backend API server. If changed, all active user login sessions are invalidated.

Example
JWT_SECRET=676765765327645bvbfgbsfhfbgr
string

The organization's email domain in DC syntax when syncing Google Groups to Retool.

Example
LDAP_BASE_DOMAIN_COMPONENTS=dc=example,dc=com
string

The mapping of Google LDAP Groups or SAML groups to Retool permission groups used for Google Group syncing and SAML role mapping.

Example
LDAP_ROLE_MAPPING=retool-admins -> admin, support -> Support

LDAP_ROLE_MAPPING_DISABLED​

string

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.

Example
LDAP_ROLE_MAPPING_DISABLED=true
string

The certificate from the downloaded bundle when syncing Google Groups to Retool.

Example
LDAP_SERVER_CERTIFICATE=filename
string

The private key from the downloaded bundle when syncing Google Groups to Retool.

Example
LDAP_SERVER_KEY=filename
string

The LDAP server name when syncing Google Groups to Retool.

Example
LDAP_SERVER_NAME=ldap.google.com
string

The LDAP server URL for Google's Secure LDAP Service when syncing Google Groups to Retool.

Example
LDAP_SERVER_URL=ldaps://ldap.google.com:636

LDAP_SYNC_ALL_GROUPS​

boolean

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.

Example
LDAP_SYNC_ALL_GROUPS=true

LDAP_SYNC_GROUP_CLAIMS​

boolean

Enable syncing Google Groups to Retool.

Example
LDAP_SYNC_GROUP_CLAIMS=true

PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN​

boolean

Prevent Retool from resetting your password when logging in with Google for the first time.

Example
PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN=true
string

Restrict users from logging in unless they use SSO for the specified domain. Specify comma-separated values for multiple domains.

Example
RESTRICTED_DOMAIN=example.com,example.org
string

The first name attribute in the SAML response.

Default value is firstName.

Example
SAML_FIRST_NAME_ATTRIBUTE=nameFirst
string

The groups attribute in the SAML response.

Default value is groups.

Example
SAML_GROUPS_ATTRIBUTE=userGroups
string

An XML document that contains information necessary for configuring SAML-enabled identity or service providers.

Example
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>"
string

The last name attribute in the SAML response.

Default value is lastName.

Example
SAML_LAST_NAME_ATTRIBUTE=nameLast

SAML_SYNC_GROUP_CLAIMS​

boolean

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.

Example
SAML_SYNC_GROUP_CLAIMS=true

SCIM_AUTH_TOKEN​

string

A secret token shared with your SSO provider to provision user accounts. If you use Spaces, this token only applies to the admin Space.

Example
SCIM_AUTH_TOKEN=token

SENDING_INVITES_WITH_EMAIL_DISABLED​

boolean

Allow user invites without pinging Retool's user invitation server. You must enable this if you have an airgapped deployment.

Example
SENDING_INVITES_WITH_EMAIL_DISABLED=true
boolean

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.

Example
TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=true
boolean

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.

Example
TRIGGER_SAML_LOGIN_AUTOMATICALLY=true