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 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.