Configure Okta SAML SSO

Learn how to configure SSO using Okta SAML.

Available on:Enterprise plan

To configure Okta SAML SSO, you must:

• Be in Admin mode in Okta.
• Have group names that match exactly between Okta and SAML.
• Have admin permissions in Retool.
• For organizations on Retool Cloud, the ability to create a custom SAML application.

Configuration

Self-hosted deployments

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, then 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 your Retool instance. Go to the Single-Sign On (SSO) > Custom SSO settings, select SAML SSO, and paste the XML file contents to the Identity Provider Metadata field.
6. If not set already, assign your app to your user in Okta.

Retool Cloud

1. Create a custom SAML application in Okta. Use the following settings.

Setting	Value
Single sign-on URL	<your-org-domain>/api/saml/login
Audience URI (SP Entity ID)	your-org-domain-without-https
firstName attribute	user.firstName
lastName attribute	user.lastName
email attribute	user.email

2. In the Feedback tab, check I'm a software vendor. I'd like to integrate my app with Okta.
3. In your app's settings, go to the Sign On tab. Under SAML Signing Certificates > SHA-2, click Actions > View IdP metadata.
4. Copy the contents of the XML file and log in to Retool. Go to the Single-Sign On (SSO) settings, select SAML SSO, and paste the XML file contents to the Identity Provider Metadata field.
5. On the same page, enter firstName and lastName in the Attributes section.
6. In your Okta app under Assignments, assign users or groups to your app.

IdP Metadata XML field in Settings

Test the connection

SSO test connection is currently in public beta on Retool Cloud and public beta for Self-hosted Retool 3.46 or later

Before saving, preview your SSO flow to ensure that the proper groups are being mapped, that the right user metadata is being sent from your identity provider, and that the integration works seamlessly.

Click the Test Connection button in your SAML SSO settings.

If SSO is configured correctly, a new tab opens and displays the login flow and the response from the SSO provider. If configured incorrectly, the new tab shows the errors that occurred.

When you're satisfied with the settings, click Save.