How do we configure Retool SSO (SAML/OIDC) with Okta or Azure AD?

Configuring Retool SSO with Okta or Azure AD lets you centralize authentication, enforce security policies, and simplify user onboarding. This guide walks through how to set up SAML or OIDC between Retool and your IdP, plus best practices to keep your configuration maintainable and secure.

1. Overview: Retool SSO with Okta and Azure AD

Retool supports enterprise-grade authentication, including:

SAML 2.0 – common for Okta and Azure AD enterprise setups
OpenID Connect (OIDC) – a modern, OAuth 2.0–based standard supported by both Okta and Azure AD

At a high level, configuring Retool SSO (SAML/OIDC) with Okta or Azure AD involves:

Creating an application in your IdP (Okta or Azure AD) for Retool.
Configuring SAML or OIDC settings (redirect URLs, audience/client IDs, etc.) in the IdP.
Entering IdP details into Retool (SSO URL, certificates, client secrets, etc.).
Testing SSO with a small set of users before rolling out fully.

Retool also supports RBAC and data-level permissions, so once SSO is in place you can leverage groups/claims for access control.

2. Prerequisites

Before you configure Retool SSO with Okta or Azure AD, make sure you have:

A Retool organization (Cloud or self-hosted).
Admin access in Retool (to configure authentication and RBAC).
Admin access to Okta or Azure AD (to create and manage enterprise applications).
A plan that supports Custom SSO (via Okta, Azure AD, or similar IdPs).

It’s also helpful to know:

Your Retool base URL (e.g., https://yourorg.retool.com or your self-hosted domain).
Whether you want to use SAML or OIDC (both are supported by Okta and Azure AD).

3. Decide: SAML vs OIDC for Retool

Both SAML and OIDC provide secure single sign-on. Which you choose for Retool SSO (SAML/OIDC) with Okta or Azure AD depends on your environment:

Choose SAML if:

Your org already standardizes on SAML for internal tools.
You rely on advanced SAML attributes for groups/roles.

Choose OIDC if:

You prefer modern, OAuth 2.0–based flows.
You want simpler token-based integration and clearer user claims.

Retool’s behavior is similar either way: users are redirected to Okta or Azure AD to sign in, then returned to Retool with a verified identity.

4. Common Retool SSO settings (SAML & OIDC)

Regardless of IdP, you’ll need to know how Retool expects certain values:

Entity ID / Audience (SAML): Usually your Retool base URL or a Retool-provided identifier.
ACS / Redirect URI: The URL in Retool that handles SSO responses, e.g.
- https://yourorg.retool.com/sso/saml/callback for SAML
- https://yourorg.retool.com/auth/oidc/callback for OIDC
NameID / Subject: Typically the user’s email address (primary identifier in Retool).
Attributes / Claims:
- email
- name or given_name / family_name
- Optional: groups or roles for RBAC

Check your Retool Authentication or SSO settings page for the exact URLs and values required in your environment.

5. Configure Retool SSO (SAML) with Okta

5.1 Create a SAML app in Okta

Sign in to Okta Admin.
Go to Applications → Applications → Create App Integration.
Choose:
- Sign-in method: SAML 2.0
Enter a name like Retool (SAML) and optionally upload a Retool logo.
Click Next to configure SAML settings.

5.2 SAML settings for Okta → Retool

In the SAML configuration screen:

Single sign on URL (ACS URL):
- Use Retool’s SAML callback URL (e.g. https://yourorg.retool.com/sso/saml/callback).
- Check “Use this for Recipient URL and Destination URL” if prompted.
Audience URI (SP Entity ID):
- Use Retool’s SAML Entity ID (commonly your Retool URL or a specific identifier; check your Retool SSO config).
Name ID format: EmailAddress
Application username: Email

Attribute Statements (examples):

Name	Name format	Value
email	Unspecified	`user.email`
name	Unspecified	`user.firstName + " " + user.lastName`
groups	Unspecified	`user.groups` (if you use group-based RBAC)

Click Next, complete feedback settings, then Finish.

5.3 Assign users and groups to Retool in Okta

In the new Retool app, go to Assignments.
Assign:
- Test users (admins) first.
- Relevant groups once you’ve validated the configuration.

5.4 Configure Retool to trust Okta (SAML)

From the Okta app’s Sign On tab, find:

Identity Provider Single Sign-On URL
Identity Provider Issuer
X.509 Certificate (download or copy PEM format)

In Retool:

Go to Settings → Authentication / SSO.
Choose SAML as the provider.
Enter:
- IdP SSO URL: the Okta SSO URL
- IdP Issuer: the Okta issuer
- X.509 Certificate: paste the certificate from Okta
Map attributes:
- Email → email
- Full Name → name (or firstName + lastName in Retool mapping, if supported)
- Groups (optional) → groups

Save your changes.

5.5 Test SAML SSO with Okta

In Okta, use “Test this application” → “Sign in as [user]” (if available).
Or go directly to your Retool URL; you should be redirected to Okta.
Confirm:
- User is created/linked in Retool.
- Group-based access appears as expected (if you use RBAC).

Once confirmed, you can enforce SSO-only login in Retool if your policy requires it.

6. Configure Retool SSO (OIDC) with Okta

6.1 Create an OIDC app in Okta

In Okta Admin, go to Applications → Applications → Create App Integration.
Select:
- Sign-in method: OIDC – OpenID Connect
- Application type: Web application
Click Next.

6.2 OIDC settings for Okta → Retool

Configure:

Sign-in redirect URIs:
- https://yourorg.retool.com/auth/oidc/callback (or as specified by Retool).
Sign-out redirect URIs (optional but recommended):
- https://yourorg.retool.com/logout or your equivalent.
Assignments: limit to specific groups or all users, depending on your policy.

After saving, note:

Client ID
Client Secret
Issuer URL (e.g., https://your-okta-domain.okta.com/oauth2/default)

6.3 Configure OIDC in Retool

In Retool Authentication / SSO:

Select OIDC (OpenID Connect) as the provider.
Enter:
- Issuer / Discovery URL: Okta Issuer URL (Retool may auto-fetch endpoints).
- Client ID: from Okta.
- Client Secret: from Okta.
- Redirect URL: confirms the one you set in Okta.
Map claims:
- Email → email
- Name → name or preferred_username
- Groups (if added as custom claim in Okta) → groups

Save and test sign-in from Retool’s login page.

7. Configure Retool SSO (SAML) with Azure AD

7.1 Create an enterprise application in Azure AD

Go to Azure Portal → Azure Active Directory → Enterprise applications.
Click New application.
Select Create your own application, name it Retool (SAML), choose Integrate any other application you don’t find (non-gallery), then Create.

7.2 Set up SAML-based sign-on

In the new application, go to Single sign-on.
Choose SAML.

Set the Basic SAML Configuration:

Identifier (Entity ID): Retool’s SAML entity ID.
Reply URL (Assertion Consumer Service URL): Retool SAML callback, e.g.
- https://yourorg.retool.com/sso/saml/callback

Optionally:

Sign-on URL: your Retool base URL.

7.3 User attributes & claims (Azure AD → Retool)

In User Attributes & Claims, ensure you send:

Unique User Identifier (Name ID):
- Source: user.mail or user.userprincipalname (commonly email).

Add or verify additional claims:

Claim name	Source attribute
email	`user.mail`
name	`user.displayname`
groups	Group claim (if needed)

If you need group-based RBAC in Retool, configure group claims (e.g., “Groups assigned to the application” or “Security groups”).

7.4 Configure Retool with Azure AD SAML details

From Azure SAML configuration, collect:

Login URL (Azure AD SSO URL)
Azure AD Identifier (Issuer)
Certificate (Base64) – the signing certificate

In Retool Authentication / SSO → SAML:

Enter:
- IdP SSO URL: Azure Login URL.
- IdP Issuer: Azure AD Identifier.
- X.509 Certificate: paste the Base64-encoded certificate.
Map attributes:
- Email → email
- Full Name → name
- Groups → groups (if configured)

Save and test with a pilot user.

8. Configure Retool SSO (OIDC) with Azure AD

8.1 Register an application for OIDC

In Azure Active Directory → App registrations.
Click New registration.
Name the app, e.g. Retool (OIDC).
Supported account types: choose according to your org (single-tenant or multi-tenant).
Redirect URI (Web):
- https://yourorg.retool.com/auth/oidc/callback

Click Register.

8.2 Configure secrets and API permissions

In the app, go to Certificates & secrets → New client secret.
- Save the Client Secret value.
Ensure default permissions include openid, profile, and email scopes.

Note:

Application (client) ID
Directory (tenant) ID

The Issuer/Discovery URL typically is:

https://login.microsoftonline.com/{tenantID}/v2.0

8.3 Configure OIDC in Retool with Azure AD

In Retool Authentication / SSO → OIDC:

Set Issuer / Discovery URL:
- https://login.microsoftonline.com/{tenantID}/v2.0
Enter:
- Client ID: Application (client) ID.
- Client Secret: the secret you created.
Claims mapping:
- Email → preferred_username or email (depending on your AAD claims).
- Name → name or given/family name claims.
- Groups (optional) → configure group claims in Azure AD and map to groups.

Save and test login from Retool’s sign-in page.

9. Using SSO with RBAC and data-level permissions in Retool

Once Retool SSO (SAML/OIDC) with Okta or Azure AD is working, you can:

Map IdP groups to Retool roles:
- Example: Okta group retool-admins → Retool Admin role.
- Example: Azure AD security group Retool-Support → a custom “Support” role in Retool.
Enforce data-level permissions:
- Use Retool’s RBAC and data-level controls so specific roles or groups can access only certain queries, environments, or resources.

Combined with audit logs and usage analytics, this lets you maintain compliance and track how authenticated users interact with your data.

10. Testing, rollout, and troubleshooting

10.1 Best practices for rollout

Pilot first: start with a small user group before enabling SSO for the entire org.
Keep a break-glass admin: retain at least one non-SSO admin login (if supported) to recover from IdP misconfigurations.
Document mappings: keep a record of group → role mappings and any custom claims used.

10.2 Common issues and checks

Users can’t sign in
- Verify the user is assigned to the Retool app in Okta/Azure AD.
- Confirm the NameID / email claim matches the email in Retool.
“Invalid audience” or “invalid issuer” errors
- Check Retool’s Entity ID / Audience exactly matches what’s in the IdP.
- Ensure the issuer URL in Retool matches the IdP’s configured issuer.
Certificate or signature problems (SAML)
- Confirm you copied the correct, active X.509 certificate from Okta/Azure AD.
- Update the certificate in Retool when the IdP cert rotates.

If you continue to see errors, review the IdP’s SSO debug logs (Okta’s System Log, Azure AD’s Sign-in logs) and Retool’s logs or error messages to pinpoint mismatched URLs, IDs, or claims.

By connecting Retool SSO (SAML/OIDC) with Okta or Azure AD, you centralize access control to your internal tools, integrate with existing policies like MFA and conditional access, and unlock granular RBAC and data-level permissions within Retool. Once configured and tested, your teams can sign in securely using the same identities they use everywhere else in your organization.