Skip to main content

Authentication environment variables

Authentication environment variables available for use with Self-hosted Retool deployments.

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).

CLIENT_ID=1234567890-abcd.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).

CLIENT_SECRET=1234567890-abcd.apps.googleusercontent.com

CUSTOM_LOGOUT_REDIRECT​

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

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

CUSTOM_OAUTH2_SSO_ACCESS_TOKEN_LIFESPAN_MINUTES​

The lifespan, in minutes, of custom OpenID provider tokens. If your OpenID Provider returns a refresh token in the initial login flow, Retool automatically uses it to refresh the access and ID tokens every two hours by default. If unset, the default lifespan is 120.

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.

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.

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.

CUSTOM_OAUTH2_SSO_ROLE_MAPPING=devops -> admin, support -> viewer

Roles set using this environment variable are case sensitive. This means:

  1. Roles set within your IdP that you pass within the variable need to match exactly. For example, if you have a Retool Admin role in your IdP, you need to pass Retool Admin.
  2. Roles within Retool are always lowercase. For example, if you have a Retool Admin role within your IdP, and you want to map it to Retool's admin role, you need to set it using Retool Admin → admin.

CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED​

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

CUSTOM_OAUTH2_SSO_ROLE_MAPPING_DISABLED=true

CUSTOM_OAUTH2_SSO_USERINFO_URL​

The endpoint for Retool 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

DEFAULT_GROUP_FOR_DOMAINS​

The default Retool user group for a Google SSO domain. You can specify space-separated values to map multiple domain and group pairs.

Default groups only applies to new users who sign up using SSO, not existing users signing in.

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.

DISABLE_USER_PASS_LOGIN=true

INVITES_PER_DAY​

The number of invites that can be sent to users. If unset, the default is 50.

Use this environment variable if you encounter rate limits on invites.

INVITES_PER_DAY=100

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

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.

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

Roles set using this environment variable are case sensitive. This means:

  1. Roles set within your IdP that you pass within the variable need to match exactly. For example, if you have a Retool Admin role in your IdP, you need to pass Retool Admin.
  2. Roles within Retool are always lowercase. For example, if you have a Retool Admin role within your IdP, and you want to map it to Retool's admin role, you need to set it using Retool Admin → admin.

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

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​

Enable syncing Google Groups to Retool.

LDAP_SYNC_GROUP_CLAIMS=true

LDAP_SERVER_URL​

When syncing Google Groups to Retool, the LDAP server URL for Google's Secure LDAP Service.

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

LDAP_SERVER_NAME​

When syncing Google Groups to Retool, the LDAP server name.

LDAP_SERVER_NAME="ldap.google.com"

LDAP_BASE_DOMAIN_COMPONENTS​

When syncing Google Groups to Retool, the organization's email domain in DC syntax.

LDAP_BASE_DOMAIN_COMPONENTS="dc=example,dc=com"

LDAP_SERVER_CERTIFICATE​

When syncing Google Groups to Retool, the certificate from the downloaded bundle.

LDAP_SERVER_CERTIFICATE=filename

LDAP_SERVER_KEY​

When syncing Google Groups to Retool, the private key from the downloaded bundle.

LDAP_SERVER_KEY=filename

PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN​

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

PRESERVE_PASSWORDS_FIRST_GOOGLE_LOGIN=true

RESTRICTED_DOMAIN​

Restrict users from logging in unless they use SSO for the specified domain. This value must match your email domain. Specify comma-separated values for multiple domains.

This removes the Retool username and password fields from the sign in page. When you deploy Self-hosted Retool, you must first sign up with a username and password. You can then enable SSO-only logins with this variable.

RESTRICTED_DOMAIN=example.com,example.org

SAML_FIRST_NAME_ATTRIBUTE​

The first name attribute in the SAML response. If unset, the default is firstName.

SAML_FIRST_NAME_ATTRIBUTE=nameFirst

SAML_LAST_NAME_ATTRIBUTE​

The first name attribute in the SAML response. If unset, the default is lastName.

SAML_LAST_NAME_ATTRIBUTE=nameLast

SAML_GROUPS_ATTRIBUTE​

The groups attribute in the SAML response. If unset, the default is groups.

SAML_GROUPS_ATTRIBUTE=userGroups

SAML_IDP_METADATA​

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

<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_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
note

When SAML_SYNC_GROUP_CLAIMS=true, users are removed from any groups that do not have a corresponding IdP group. This includes users assigned to the Admin group. If you enable this setting, test the signin flow with a non-admin or test user.

SCIM_AUTH_TOKEN​

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

SCIM_AUTH_TOKEN=token

SCIM_LOG_FULL_REQUESTS​

Log SCIM requests to the Retool API container logs.

SCIM_LOG_FULL_REQUESTS=true

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

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.

TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=true
TRIGGER_SAML_LOGIN_AUTOMATICALLY=false

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.

TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY=false
TRIGGER_SAML_LOGIN_AUTOMATICALLY=true

USE_SHORT_SESSIONS​

Restrict session length to 12 hours. If unset, default session length is one week.

USE_SHORT_SESSIONS=true