Skip to main content

Configure SSO with SAML authentication

Learn how to configure SSO with providers using SAML.

Retool Cloud and Self-hosted Retool deployments support Okta, Microsoft Entra ID, Active Directory Federation Services, and other SAML SSO providers.

If you don't use Okta or Active Directory, use the following steps to configure your SAML identity provider service.

1. Set your Entity ID in Retool​

By default, Retool uses the Entity ID https://tryretool.com.

2. Configure your Identity Provider​

You should reference the provided documentation from your identity provider to complete its setup. However, you will likely be asked to supply values for the Sign on URL and Reply URL fields. Use the following pattern, replacing retool.yourcompany.com with the Entity ID you supplied in step 1:

  • Sign on URL: https://retool.yourcompany.com/api/saml/login
  • Reply URL: https://retool.yourcompany.com/api/saml/login

3. Match user attributes and claims​

Retool requires exactly the following attributes to be asserted for each user on login:

  • email: The identifier for a user
  • firstName: The user's first name
  • lastName: The user's last name

4. Assign users access to Retool​

Use your identity provider to assign users to have access to login to Retool.

5. Configure Retool with the Identity Provider Metadata​

Export the metadata to an XML file from your identity provider and copy it. There's usually a button to trigger a download from your IdP dashboard. Additionally, you can often find this data by navigating to https://your.identityprovider.com/federationmetadata/2007-06/federationmetadata.xml.

You can configure Retool with the IdP metadata in the dashboard for Retool Cloud, or with the SAML IDP METADATA environment variable on self-hosted deployments. To use the dashboard, log in to Retool as an admin user.

On Retool Cloud, go to Settings > Single Sign-On (SSO), select SAML SSO, and paste the XML file contents to the Identity Provider Metadata field. On self-hosted deployments, this setting is on Settings > Advanced.

Configuring Identity Provider Metadata in Retool

6. Test the connection​

Once you've configured your settings, click Save Changes. To test the integration and its settings, click the Test Connection button.

This triggers a simulation of the SSO flow that ensures that the proper groups are mapped, the right user metadata is sent from your identity provider, and the integration works seamlessly. Clicking the Test Connection button does not change the current user's permission groups, and you won't be locked out if SSO is misconfigured.

After Retool tests the connection, a new tab opens and displays the Connection Status, Issues Detected, and Connection Details. If there are any issues, this page displays warnings and recommendations to resolve them. You can see the full response from the SSO provider in the Connection Details section.

Once you are satisfied with your configuration, log out of Retool and log back in using SSO to test the flow yourself.

If you use a self-hosted deployment and updated your environment variables, restart your Retool instance.