Configure Microsoft Entra ID SAML SSO
Learn how to configure SSO with Microsoft Entra ID SAML.
Follow these steps to configure SAML SSO with Microsoft Entra ID for your Retool instance.
1. Set your Entity ID in Retool
- Retool Cloud
- Self-hosted Retool
By default, Retool uses the Entity ID https://tryretool.com.
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 Microsoft Entra ID Enterprise application
In the Microsoft Entra ID admin center, add a new Enterprise application. Retool is not listed in the Microsoft Entra ID Gallery, so you must select Create your own application.
Name the application “Retool” and select Integrate any other application you don’t find in the gallery (Non-gallery).
3. Assign users to the Retool application in Azure
For users to access Retool using Microsoft Entra ID 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 Microsoft Entra ID admin center.
4. Configure SAML settings in Azure
In the Microsoft Entra ID 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, replacing yourcompany.com with your domain. Leave Relay state and Logout URL blank.
| Setting | Value |
|---|---|
| Identifier (Entity ID) | retool.yourcompany.com |
| Reply URL (Assertion Consumer Service URL) | On Retool Cloud, https://your-company.retool.com/api/saml/login. On self-hosted Retool, https://retool.your-company.com/saml/login. |
| Sign on URL | On Retool Cloud, https://your-company.retool.com/api/saml/login. On self-hosted Retool, https://retool.your-company.com/saml/login. |
Set the following attributes and claims.
| Setting | Value |
|---|---|
| Unique User Identifier (Name ID) | user.mail |
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 you configured SAML settings in the Microsoft Entra ID 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.
- Self-hosted Retool: Go to Settings > Advanced.
- Retool Cloud: Go to Settings > Single Sign-On (SSO), select SAML SSO, and paste the XML file contents to the Identity Provider Metadata field.
6. Test the integration
Navigate to the /auth/login page for your Retool instance and click Sign in with SSO. 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.