Skip to main content

SSO best practices

Recommendations for configuring, testing, and operating SSO.

These SSO best practices are organized around reducing risk of lockout, and around keeping group membership and session behavior correct once SSO is working.

Test SSO before you enforce it​

Configure and verify SSO end-to-end while email and password login still works, and then disable the fallback.

Retool provides a test flow from the SSO settings page that reports failures at /settings/sso-test?error=<message> without affecting anyone's ability to sign in. Use it to confirm a real login succeeds, that the email attribute arrives, and that groups map the way you expect.

Enforcing SSO before testing is the most common way organizations lose access to their own instance.

Know your recovery path before you enforce SSO​

Enforcing SSO removes the email and password fallback, so a locally authenticating administrator account can't sign in either once enforcement is on. The recovery path is a procedure rather than a spare login, and it differs by hosting:

  • Self-hosted: Set DISABLE_USER_PASS_LOGIN to false and clear RESTRICTED_DOMAIN to restore the password form. Set TRIGGER_SAML_LOGIN_AUTOMATICALLY and TRIGGER_OAUTH_2_SSO_LOGIN_AUTOMATICALLY to false to stop the automatic redirect into the identity provider.
  • Cloud: Contact Retool support, who can restore the password login path for your organization.

Write the relevant path down somewhere your team can reach it during an outage, and confirm the people who'd need to run it actually have the access to do so. Refer to Troubleshooting SSO for the full recovery steps.

Test group sync with a non-administrator account​

Group sync applies on every login, which removes and adds memberships. If your identity provider's claim doesn't include the group that grants you admin, Retool takes you out of it on your next sign-in.

Verify the claim contents against a test user who has nothing to lose before letting sync run against administrator accounts.

Map groups by intent​

Retool matches groups by name, so an identity provider group called retool-admins doesn't reach a Retool group called Retool Admins unless you map it explicitly using role mapping.

Decide the naming convention once, apply it on both sides, and document it. Mapping groups one at a time as they come up can lead to a state where nobody can say with confidence which identity provider group grants which Retool permission.

Use SCIM as the source of truth for accounts​

JIT provisioning creates an account on first successful login, which is convenient, but one-directional. When someone leaves the company, the account persists until an administrator removes it manually.

SCIM user provisioning keeps Retool accounts aligned with your identity provider, which pushes changes into Retool as they happen. When your identity provider deactivates a user, Retool disables the account, and a disabled account can't authenticate.

Deprovisioning is the reason to prefer SCIM, however, the identity provider only sends the deactivation if you enable that operation on its side. For example, in Okta, that means enabling Deactivate Users under To App in the app's provisioning settings, alongside Create Users and Update User Attributes. If this is not enabled in Okta, SCIM still creates and updates accounts, so provisioning looks healthy while departed users keep working access. Verify deactivation end-to-end with a test user before you rely on it.

If your organization's plan includes SCIM, use it to decide which users exist and let JIT provisioning cover only the cases SCIM doesn't.

Restrict sign-in domains​

Set a restricted domain list so only email addresses on domains you control can authenticate, even if someone is assigned the Retool application in your identity provider by mistake.

Set the domain alone, with no protocol and no subdomain. The value matches the email addresses users sign in with, not the hostname where Retool is deployed. Refer to Restrict sign-in domains.

Adjust session length​

Retool's default session length suits most organizations. Shorten it when Retool apps can access sensitive data, or when access is shared. Refer to Configure short sessions.

Track certificate expiry​

SAML signing certificates expire, and when one does, every login fails at once with a parser error. Record the expiry date when you configure the connection, and set a reminder to rotate your certificate on a set schedule.

Configure SSO in one place​

On self-hosted instances, SSO can be configured through the Settings page or through environment variables. A setting that looks correct in the UI can be overridden by environment variables.

Pick one way to configure and stick with it. If you use environment variables, treat the Settings page as read-only. Refer to Environment variables for the full list.