Configure SSO with SAML authentication

📘

SSO with SAML is only available on the Enterprise plan with Self-hosted Retool. You can book a demo with our team to learn more.

Self-hosted Retool deployments support Okta, Active Directory, and other SAML SSO providers.

Okta

You must be in Admin mode to configure Okta and have admin permissions in Retool. To set up Okta as your identity provider:

1. In your Okta admin dashboard, click Add Application.
2. Search for Retool and follow the wizard.
3. Navigate to the Okta application you created. Click on the Sign On tab, and then on Actions > View IdP Metadata in the SAML Signing Certificates section.
4. Save the page as an XML file. Consult Okta's documentation to confirm how to view the IdP metadata.
5. Copy the contents of the XML file and log in to Retool. Navigate to Settings > Advanced and paste the XML file contents to the IdP Metadata XML field under SSO and User Provisioning.

Azure Active Directory

1. Customize your Entity ID in Retool

• By default, Retool uses the Entity ID https://tryretool.com. You need to customize this value to match the domain where you're hosting Retool.
• Add the following environment variable to your docker.env file, replacing retool.yourcompany.com with your domain. Note: adding a new environment variable requires restarting the container for it to take effect.

DOMAINS=retool.yourcompany.com

2. Create an Azure Active Directory Enterprise application

• In the Azure Active Directory admin center, add a new Enterprise application
• Retool is not listed in the Azure AD Gallery, so you must select “Create your own application”
  • Name the application “Retool”
  • Select Integrate any other application you don’t find in the gallery (Non-gallery)

3. Assign users to the Retool application in Azure

In order for users to access Retool using Azure Active Directory SSO, they must:

• Be assigned to the application
• Have a First Name, Last Name, User Principal Name, and Email defined on their profile

Assign users to the Retool application and confirm their required attributes in the Azure Active Directory admin center.

4. Configure SAML settings for the Retool application in Azure

• In the Azure Active Directory admin center, select the Retool Enterprise application
• Set up single sign on for the Retool application, selecting SAML as the sign-on method
• Use the following SAML settings:
  • Basic SAML Configuration (replace retool.yourcomany.com with the domain name assigned to your Retool instance):
    • Identifier (Entity ID): retool.yourcompany.com
    • Reply URL (Assertion Consumer Service URL): https://retool.yourcompany.com/saml/login
    • Sign on URL: https://retool.yourcompany.com/saml/login
    • Relay State: leave blank
    • Logout URL: leave blank
  • Attributes & Claims:
    • Required claim
      • Unique User Identifier (Name ID): user.mail
    • Additional claims (delete default claims first)
      • firstName: user.givenname
      • lastName: user.surname
      • email: user.userprincipalname

You must also edit each claim and clear the value for the Namespace field.

5. Import Azure Federation Metadata into Retool

• On the same page where you configured SAML settings in the Azure Active Directory admin center, download the Federation Metadata XML file (listed under the SAML Signing Certificate).
• Open the XML file in a code editor and copy the contents to your clipboard.
• Log in to Retool as an admin user.
• Navigate to the Settings > Advanced page and paste the XML data to the IdP Metadata XML field. Save your changes.

6. (Optional, but recommended) Turn on JIT User Provisioning

Just in time (JIT) user provisioning enables Retool to provision user accounts when users sign in via SAML for the first time. This means you won't have to manually invite each user to Retool first. To turn this on, simply toggle the switch on the Settings > Advanced page.

7. Test the integration

• Navigate to the /auth/login page for your Retool instance.
• Click the Sign in with SSO button.
• Retool redirects you to login.microsoft.com where you are prompted for credentials.
• After entering credentials for a user who is assigned to the Retool app in Azure, you are redirected back to Retool and logged into the instance.

Active Directory Federation Services

Another common Identity Provider is Active Directory Federation Service. Below is a step-by-step guide for integrating Retool with ADFS 3.0

1. Single sign on URL For Step 7 (Configure URL) you will need your Retool's Single Sign on URL. This will typically be https://retool.yourcompany.com/saml/login

2. Welcome: Open up the AD FS Manager, and start the Add Relying Party Trust Wizard

3. Select Data Source: Select "Enter data about the relying party manually"

4. Specify Display Name: Enter in a description in the next step for Retool in the next screen.

5. Choose Profile: Choose the AD FS Profile, as Retool supports SAML 2.0

6. Configure Certificate: Skip the next step (do not provide an optional token encryption certificate)

7. Configure URL: Choose the "Enable support for SAML 2.0 WebSSO Protocol. For the entry box for "Relying party SAML 2.0 SSO service URL" use the following pattern: https://domain.of.onprem.retool/saml/login You may find this URL in the settings page of Retool where you can export Retool's Service Provider Metadata (see Step 1).

8. Configure Identifiers: The Relying Party trust identifier should be of the form retool.yourcompany.com

🚧

The trust identifier must exclude protocol formatting

Incorrect: https://subdomain.domain.com/ > Correct: subdomain.domain.com

9. Finish wizard: Continue and press next for all the following steps in the wizard.

10. Edit Claim Rules We will create two rules in the Issuance Transform Rules section now.

11. First claim - Select "Send LDAP Attributes as Claims", and use the following screenshot as a guide.

12. Second claim Select "Transform an Incoming Claim" and use the following screenshot as a guide.

13. Save all settings.

14. Configure Retool with the Identity Provider Metadata
    Export the metadata to an XML file from your IdP. There is usually a button to trigger a download this from your IdP dashboard. Additionally, you can often find this by navigating to https://your.identityprovider.com/federationmetadata/2007-06/federationmetadata.xml.`

Copy the entire XML file to your clipboard and login to Retool as an admin user. Navigate to the Settings > Advanced page and add the copied XML file to the IdP Metadata XML field.

Other SAML Identity Providers

If you don't use Okta or ADFS, 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. You will need to customize this value to match the domain where you're hosting Retool.

Add the following environment variable to your docker.env file, replacing retool.yourcompany.com with your domain. Note: adding a new environment variable requires restarting the container for it to take effect.

DOMAINS=retool.yourcompany.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/saml/login
• Reply URL: https://retool.yourcompany.com/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. 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.

Copy the entire XML file to your clipboard and login to Retool as an admin user. Navigate to the Settings > Advanced page and paste the XML data to the IdP Metadata XML field.

6. Enable JIT user provisioning

This step is optional, but recommended.

Just in time (JIT) user provisioning enables Retool to provision user accounts when users sign in via SAML for the first time. This means you won't have to manually invite each user to Retool first. To turn this on, toggle the switch on the Settings > Advanced page.