Skip to main content

Troubleshooting SSO

Diagnose and resolve common issues with SSO authentication, group sync, and user provisioning.

Retool reports most SSO failures by redirecting back to the login page with the reason in the URL, as /auth/login?error=<message>. If you're testing the connection from the SSO settings page rather than signing in, the same message appears at /settings/sso-test?error=<message> instead. Either way, read that URL message first: it names the specific check that failed, and the sections below are organized around those messages.

Why can't anyone log in after I enabled SSO?​

Two settings remove the email and password fallback. Turning either on before SSO actually works locks out every user, administrators included.

  • Disable Login with Email and Password removes the email and password form entirely.
  • Trigger Login Automatically redirects users into the SSO flow as soon as they reach your instance, so they never reach the form even while it's still enabled.

Both settings live on the Single Sign On (SSO) settings page. If you can still reach the login form as an administrator, turn them off there.

If no one can reach the form at all, contact Retool support. Retool can restore the password login path for your organization.

To avoid this entirely, confirm users can complete a full SSO login (not just a successful test connection) before enforcing it. Refer to Enforce SSO for the full sequence.

Why do I get "The email must be specified as a SAML attribute"?​

Retool identifies users by email address and requires it as an attribute on every SAML assertion. Your identity provider is either omitting the attribute or sending it under a different name.

Configure your identity provider to send the user's email address in an attribute named email. Refer to your provider's tutorial for the exact field:

Why do I get "SAML response Destination does not match the configured ACS URL"?​

The Destination attribute in the SAML response doesn't match the Assertion Consumer Service URL Retool expects. This almost always means the identity provider was configured against a different hostname than the one users actually reach.

Check these in order:

  1. The ACS URL registered with your identity provider matches your Retool instance's hostname exactly, including protocol and any port.
  2. If you use a custom domain, the identity provider points at the custom domain rather than the default one.
  3. Your load balancer or reverse proxy forwards the original host header. A proxy that rewrites the host makes Retool build an ACS URL that no longer matches the one the identity provider was given.

Why do I get "Authentication request expired or could not be verified"?​

Retool binds each SAML response to the authentication request that started it, and rejects responses it can't match to an outstanding request.

Common causes:

  • The user started the login in one browser tab and finished it in another after the original request expired. Ask them to start again from the login page.
  • Cookies are blocked or stripped between Retool and the browser. Retool stores the outstanding request in a cookie, so a proxy or browser setting that drops it breaks the binding.
  • The user initiated the flow from a bookmarked identity provider URL. Service provider initiated login must start at Retool.

A closely related message, SAML response has already been used. Please re-authenticate to obtain a new response., means the same assertion was submitted twice. Retool consumes each assertion once, so have the user start a fresh login rather than refreshing or resubmitting.

Why do I get "Authentication failed" with a parser error?​

Retool couldn't parse or validate the SAML response, and appends the underlying reason to the message. Certificate mismatch and clock skew are the most common causes.

  1. Confirm the certificate configured in Retool is the current signing certificate from your identity provider. Certificates rotate, and an expired or superseded one fails validation.
  2. Confirm the system clocks on both sides are synchronized. SAML assertions carry a narrow validity window, and a few minutes of drift invalidates them.
  3. Confirm the identity provider signs the assertion, the response, or both, in whatever combination Retool is configured to expect.

Why do new users get told to ask an admin for an invite?​

The full message is Looks like you need to ask a Retool admin to invite you to Retool first! Alternatively, you can ask a Retool admin to enable Just-In-Time user provisioning in the settings page.

The user authenticated successfully but has no Retool account, and just-in-time provisioning is turned off. Either invite the user manually, or enable JIT user provisioning so Retool creates accounts on first successful login.

Why do new users get a payment error when logging in?​

Your organization has reached its seat limit, and Retool refuses to create the account rather than exceeding it. The exact message depends on your plan and names the limit it hit, such as Your license has a maximum of <n> seats.

Refer to User seats to review current usage, and to Troubleshooting users and organizations for how seat counting works.

Why do I get "Cannot login via SAML. Domain for [email] not allowed"?​

A restricted domain list is configured, and the user's email domain isn't on it. Retool blocks the login before creating or matching an account.

Update Restricted Domains on the Single Sign On (SSO) settings page. It accepts a comma-separated list of domains.

Refer to Restrict sign-in domains for more detail.

Why do I get "User [email] is already registered in a different organization"?​

The email address belongs to an account in another Retool organization. An email address can only belong to one organization at a time.

Have the user remove their account from the other organization, or use a different email address for this one.

Why do I get "Your account was disabled"?​

An administrator disabled the account. SSO authentication succeeds, but Retool refuses the session. An administrator can re-enable the account from the Users settings page.

Why aren't users landing in the right permission groups?​

Group sync maps a claim from your identity provider onto Retool permission groups. When the mapping is wrong, users authenticate successfully but arrive with no groups or the wrong ones.

Check these in order:

  1. The attribute name matches. Retool reads SAML groups from the attribute named by SAML_GROUPS_ATTRIBUTE, which defaults to groups. For OIDC, the equivalent is CUSTOM_OAUTH2_SSO_JWT_ROLES_KEY. If your identity provider sends groups under a different name, Retool finds nothing.
  2. The values match your Retool group names. Mapping is by name, so a group your identity provider calls retool-admins doesn't match a Retool group called Retool Admins unless you map it explicitly.
  3. The user is actually in the group on the identity provider side. Membership changes there don't reach Retool until the user's next login.

Group sync applies on each login, so a user whose groups changed in the identity provider keeps their old Retool groups until they sign in again.

On self-hosted instances, environment variables override the equivalent fields on the SSO settings page. If the page shows the value you expect but sync still behaves differently, check whether an environment variable is overriding it.

Group sync can remove admin access

If group sync runs and the claim doesn't include your administrator group, Retool removes the user from it. Combined with disabled password login, this locks administrators out of their own instance. Test group sync with a non-administrator account first. If you're already locked out, refer to Why can't anyone log in after I enabled SSO? for how to recover access.

For provider-specific configuration, refer to Sync groups from your identity provider.

Why did LDAP group sync stop working?​

Errors prefixed with [LDAP] come from Retool's connection to your LDAP directory rather than from the SAML exchange itself:

ErrorCause
[LDAP] - Error connecting LDAP clientRetool couldn't reach or authenticate against the LDAP server. Check LDAP_SERVER_URL, the bind credentials, and that your network allows the connection.
[LDAP] - Error finding groupsRetool connected, but the group search returned an error. Check LDAP_BASE_DOMAIN_COMPONENTS and your role mapping configuration.

A user can still authenticate through SAML while LDAP group lookup fails, so this surfaces as missing groups rather than a failed login.

Why did Sign in with Google stop working after I added a custom domain?​

Google SSO is registered against a specific hostname. Adding or changing a custom domain after configuring Google SSO breaks the redirect flow, because the values on both sides no longer agree on which hostname to use.

Check these in order:

  1. The Google OAuth client's authorized origins and redirect URIs list the custom domain. These are set in the Google APIs console, and don't update automatically when you add a custom domain. Refer to Configure Sign in with Google for the exact values.
  2. On self-hosted instances, BASE_DOMAIN should match the custom domain. Retool uses this variable to build the redirect URIs it sends to Google. A BASE_DOMAIN still pointing at the original hostname sends users to a redirect URI Google no longer recognizes.
  3. The custom domain finished provisioning. A domain still in a pending state in Branding settings can intermittently fail SSO until provisioning completes.

Why does DEFAULT_GROUP_FOR_DOMAINS have no effect?​

DEFAULT_GROUP_FOR_DOMAINS only applies to Sign in with Google. It has no effect on SAML, custom OIDC, or LDAP, even when those are also configured for the same organization. If you're provisioning users through a custom OAuth or SAML identity provider, use JIT user provisioning to assign a default group instead.

Why do OIDC users get logged out and asked to reauthenticate more often than expected?​

Retool refreshes an OIDC session using a refresh token. When the identity provider doesn't issue one, Retool can't refresh the session and falls back to the token's original expiration, which is often much shorter.

Confirm offline_access is included in the scopes Retool requests. On cloud instances and self-hosted instances on version 3.16 and later, add it in the Scopes field on the SSO settings page. On earlier self-hosted instances, add it to the CUSTOM_OAUTH2_SSO_SCOPES environment variable. Refer to Custom OIDC for provider-specific scope values, since some identity providers require offline_access to be enabled separately from the scope list before they'll issue a refresh token at all.

Why do Google SSO and Custom SSO sessions last different lengths of time?​

Session duration is a single setting that applies to SSO sessions generally, one week by default or 12 hours with Use short session enabled. If Google SSO and custom SAML or OIDC sessions on the same organization appear to expire at different rates, the difference isn't the session duration setting; it's usually the OIDC refresh-token issue above, where a missing offline_access scope makes custom OIDC sessions end sooner than the configured duration rather than lasting the full duration like Google SSO does.

Why does SSO work for some users but not others?​

When only a subset of users fail, the difference is almost always on the identity provider side rather than in Retool's configuration.

Compare a working user against a failing one:

  • Is the failing user assigned to the Retool application in your identity provider? Unassigned users are rejected before Retool sees them.
  • Does the failing user have an email address populated on their identity provider profile? Retool rejects assertions without one.
  • Is the failing user's email domain on your restricted domain list?
  • Does the failing user already have an account in a different Retool organization?