Skip to main content

Migrate from SAML to OIDC

Learn how to migrate your SSO configuration from SAML to OIDC.

Available on:Enterprise plan

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.