Migrate from SAML to OIDC
Learn how to migrate your SSO configuration from SAML to OIDC.
| Single Sign-On (SSO) Availability | |||
|---|---|---|---|
| Cloud | Generally Available | ||
| Self-hosted Edge 3.36 or later | Generally Available | ||
| Self-hosted Stable 3.33 or later | Generally Available | ||
You can use both OpenID and SAML SSO methods to log users in to Retool. OIDC SSO has additional functionality you may want to enable based on your use case. For example, with OIDC, you can use ID tokens from your IdP for authentication in Retool resources.
On self-hosted instances, ensure you follow the order outlined in this guide. On Retool Cloud, you can update settings directly in Settings > Single Sign-On (SSO).
To minimize downtime, apply all changes to environment variables at the same time. When you restart the Retool server, your instance immediately replaces the SAML-based SSO with the new OIDC-based SSO.
1. Enable OIDC SSO
Use the configuration guides—Okta, Google, OneLogin, or another provider—to enable OIDC authentication on your instance. This involves creating an OIDC app for your Retool instance and setting CUSTOM_OAUTH2_SSO_* environment variables. You can set these variables in Retool under Settings > Configuration variables. Do not restart your Retool instance yet.
2. Remove SAML metadata
If you store SAML metadata in the Retool settings UI, ensure you added the OIDC configuration in the previous step. Settings stored in the UI are applied immediately.
SAML IDP metadata is located in either the Settings > Advanced page in the Retool UI, or stored in the SAML_IDP_METADATA environment variable. Remove or comment out the metadata.
3. Restart your Retool instance
Restart your Retool instance and select Login with SSO to test your changes. If you cannot log in, comment out the RESTRICTED_DOMAIN environment variable to temporarily enable username and password logins. Confirm the rest of your environment variables are correctly set. You may also want to enable JIT user provisioning.