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

Configuring Retool SSO (SAML or OIDC) with Okta or Azure AD lets you centralize authentication, enforce stronger security (MFA, conditional access), and manage access to internal tools with enterprise-grade controls. This guide walks through the concepts, prerequisite setup, and step-by-step configuration patterns for both Okta and Azure AD, for both SAML and OIDC.

---

1. How Retool SSO (SAML/OIDC) Works

Retool supports enterprise SSO so your users can sign in with their identity provider (IdP) instead of separate credentials. At a high level:

• SAML: Browser-based authentication using SAML 2.0 assertions. The IdP sends a signed SAML response containing the user identity and optional group/role attributes.
• OIDC (OpenID Connect): A modern authentication layer on top of OAuth 2.0. Retool trusts ID tokens returned by the IdP and uses scopes/claims to identify the user and roles.

Benefits for Retool:

• Centralized login with Okta or Azure AD
• Strong security: MFA, device checks, conditional access
• RBAC and data-level permissions managed via groups and attributes
• Works the same whether you use Retool Cloud or self-hosted deployments

Note: Details like exact field names and UI labels can change between Retool versions. Use this guide as the conceptual map; follow your Retool admin UI for exact labels.

---

2. Prerequisites

Before configuring SAML or OIDC SSO with Okta or Azure AD for your Retool organization, you should have:

• Retool admin access
  • You must be an admin in your Retool instance (cloud or self-hosted) to configure SSO.
• Identity Provider admin access
  • Admin rights to Okta or Azure AD to:
    • Create an enterprise application
    • Configure SAML/OIDC settings
    • Assign users/groups to the app
• Retool base URL
  • Retool Cloud: https://your-org.retool.com (or similar)
  • Self-hosted: your custom domain, e.g. https://apps.yourcompany.com
• Decisions on SSO behavior
  • Will you use SAML or OIDC?
  • Will you use Just-in-Time (JIT) provisioning or pre-create users?
  • How will you map groups/roles from Okta/Azure AD to Retool permissions?

---

3. General Setup Flow (Any IdP, SAML or OIDC)

Regardless of whether you use Okta or Azure AD and SAML or OIDC, the steps follow the same pattern:

1. Create an application in your IdP:
   • Choose the protocol (SAML 2.0 or OIDC).
   • Set the redirect/callback and audience/identifier to your Retool URL.
2. Configure SSO settings in Retool:
   • Enable SAML or OIDC.
   • Paste the required metadata from the IdP (SAML) or endpoints/client credentials (OIDC).
3. Map user identity attributes:
   • Email
   • Name
   • Optional: groups, roles, department, etc.
4. Configure RBAC in Retool:
   • Map IdP groups to Retool roles, environments, or data-level permissions.
5. Test login:
   • Use a test user assigned to the app.
   • Verify successful login, correct role assignment, and logging/auditing.
6. Roll out:
   • Assign the app to your wider user base.
   • Optionally enforce SSO-only access.

Retool supports enterprise-grade security including SSO, RBAC, data-level permissions, audit logs, and source control, so making SSO your primary access point is a recommended best practice for larger teams.

---

4. Configure SAML SSO with Okta

4.1 Create a SAML 2.0 application in Okta

1. Log in to Okta Admin Console.
2. Navigate to Applications → Applications → Create App Integration.
3. Choose:
   • Sign-in method: SAML 2.0
4. Click Next, then configure the app:
   • App name: e.g. Retool (SAML)
   • Optionally upload a Retool logo and click Next.

4.2 Configure SAML settings in Okta

In the SAML Settings:

• Single sign-on URL (ACS URL):
  • Typically: https://your-org.retool.com/saml/callback
    (for self-hosted, use your own domain)
• Audience URI (SP Entity ID):
  • Often your Retool base URL or a specific entity ID given in Retool’s SAML settings (e.g. https://your-org.retool.com/saml/metadata or an SP identifier string).
• Name ID format:
  • EmailAddress is common.
• Application username:
  • Email (preferred).

Add attribute statements (used by Retool to understand the user):

Example attribute mappings:

Okta Attribute	Name (SAML Attribute)	Value (Okta expression)
Email	email	user.email
Full name (or first)	name	user.firstName + " " + user.lastName
Groups (optional)	groups	String.join(",", user.groups)

Click Next, then choose "I'm an Okta customer adding an internal app" and Finish.

4.3 Get SAML metadata from Okta

In the new app:

1. Go to the Sign On tab.
2. Find SAML 2.0 section and click View Setup Instructions or Identity Provider metadata.
3. Copy:
   • Identity Provider Single Sign-On URL
   • Identity Provider Issuer
   • X.509 Certificate
     Or download the IdP metadata XML if Retool supports direct metadata upload.

4.4 Configure SAML SSO in Retool

In Retool (as an admin):

1. Go to Settings → Authentication / SSO (label may vary) and choose SAML.
2. Enter:
   • IdP SSO URL: from Okta.
   • IdP Issuer: from Okta.
   • X.509 Certificate: from Okta.
   • SP Entity ID / Audience: match what you used in Okta.
   • ACS URL: confirm it matches what you configured in Okta.
3. Configure attribute mapping:
   • Email attribute: email
   • Name attribute: name
   • Group attribute: groups (if using group-based RBAC).
4. Save the configuration.
5. Optionally:
   • Enable Just-in-Time provisioning so users are created on first SSO login.
   • Specify allowed domains for email addresses.

4.5 Map Okta groups to Retool roles

To leverage Retool’s RBAC and data-level permissions:

1. In Okta:
   • Create or use existing groups (e.g. retool-admins, retool-editors, retool-viewers).
   • Assign these groups to the Retool SAML app.
2. In Retool:
   • In the SSO configuration or RBAC area, map:
     • retool-admins → Retool Admin role
     • retool-editors → Editor / Developer role
     • retool-viewers → Viewer role
   • Optionally use group attributes to limit access to specific apps, environments, or data-level rules.

4.6 Test Okta SAML SSO

1. In Okta, assign the Retool app to a test user.
2. Log out of Retool (or use a fresh browser/incognito).
3. Go to your Retool URL and click Sign in with SSO (or a SAML button, if configured).
4. Authenticate via Okta and ensure:
   • You can sign in successfully.
   • Your email and name appear correctly.
   • Your Retool role matches the intended group mapping.

Once verified, roll out to your broader user base.

---

5. Configure OIDC SSO with Okta

If you prefer OIDC, the flow is similar but uses OAuth/OIDC endpoints and client credentials.

5.1 Create an OIDC application in Okta

1. In Okta Admin Console, go to Applications → Create App Integration.
2. Choose:
   • Sign-in method: OIDC – OpenID Connect
   • Application type: Web
3. Click Next, then configure:

• App name: Retool (OIDC)
• Sign-in redirect URIs:
  • https://your-org.retool.com/oauth/callback (or the OIDC callback URL shown in Retool)
• Sign-out redirect URIs (optional):
  • your Retool base URL.

Save and note the Client ID and Client Secret.

5.2 Configure OIDC details in Okta

In the OIDC app:

• Ensure:
  • Grant types include Authorization Code.
  • Login redirect URIs match Retool’s configured callback.
  • Assignments: Assign users/groups who should access Retool.

5.3 Configure OIDC SSO in Retool

In Retool admin settings:

1. Enable OIDC.
2. Enter:
   • Issuer URL: Okta org URL with /oauth2/default or a custom auth server, e.g.
     https://yourcompany.okta.com/oauth2/default
   • Authorization endpoint: Typically derived from the issuer (Retool may auto-discover from the issuer’s .well-known/openid-configuration).
   • Token endpoint: From Okta’s OIDC configuration.
   • JWKS URI: For token verification (usually auto-discovered).
   • Client ID and Client Secret: From the Okta app.
   • Scopes: include openid, profile, email (and group scopes if needed).
3. Attribute mapping:
   • Email claim: email
   • Name claim: name (or given_name + family_name)
   • Groups: groups or a custom claim.

Save and test login as described in the SAML section.

---

6. Configure SAML SSO with Azure AD

6.1 Create an Enterprise Application

1. Go to Azure Portal → Azure Active Directory → Enterprise applications.
2. Click New application → Create your own application.
3. Name it, e.g. Retool (SAML).
4. Choose Integrate any other application you don’t find in the gallery.
5. Click Create.

6.2 Configure SAML SSO in Azure AD

1. Open your new app, go to Single sign-on.
2. Choose SAML.
3. Under Basic SAML Configuration, click Edit and set:
   • Identifier (Entity ID):
     • Your Retool SP Entity ID (often your Retool URL or a specific ID from Retool).
   • Reply URL (Assertion Consumer Service URL):
     • https://your-org.retool.com/saml/callback
   • Sign-on URL (optional):
     • Your Retool URL.

Save.

6.3 Configure User Attributes & Claims

Under User Attributes & Claims:

• Ensure:
  • user.userprincipalname or user.mail is mapped to the Name ID as an email.
• Add custom claims if needed:

Example:

Claim name	Source attribute
email	user.mail
name	user.displayname
groups	user.groups (or use group IDs and map in Retool)

Note: For groups, you may need to enable group claims in Azure AD and decide whether to send group names or IDs. Retool can use either, but names are easier to map.

6.4 Download Azure AD SAML metadata

In the SAML configuration page, download the Federation Metadata XML or copy:

• Login URL
• Azure AD Identifier
• Logout URL (optional)
• Certificate (Base64)

6.5 Configure SAML in Retool

In Retool admin:

1. Enable SAML SSO.
2. Enter:
   • IdP SSO URL: Azure AD Login URL.
   • IdP Issuer: Azure AD Identifier.
   • X.509 Certificate: Certificate from Azure AD.
   • SP Entity ID / Audience: match Azure AD Identifier configuration.
   • ACS URL: should match the Reply URL you set in Azure AD.
3. Map attributes:
   • Email: email
   • Name: name
   • Groups: groups (if used).

Save the configuration.

6.6 Assign Users and Groups in Azure AD

1. In the Azure AD app, go to Users and groups.
2. Assign:
   • Individual users, and/or
   • Azure AD security groups (e.g. Retool-Admins, Retool-Editors, Retool-Viewers).

In Retool, map these groups to roles and permissions as desired (similar to the Okta group mapping approach).

6.7 Test Azure AD SAML SSO

1. Use Test this application in the Azure AD SAML config page or sign in via your Retool URL.
2. Confirm:
   • Successful login.
   • Email, name, and group mappings are correct.
   • Proper Retool role assignment.

---

7. Configure OIDC SSO with Azure AD

7.1 Register an application

1. Go to Azure Portal → Azure Active Directory → App registrations.
2. Click New registration.
3. Set:
   • Name: Retool (OIDC)
   • Supported account types: as required (e.g. Single tenant or multi-tenant).
   • Redirect URI (web):
     https://your-org.retool.com/oauth/callback (or the OIDC callback shown in Retool).
4. Click Register.

7.2 Configure API permissions and secrets

1. In the new app, go to Certificates & secrets:
   • Create a client secret and copy it.
2. Keep the:
   • Application (client) ID
   • Directory (tenant) ID

7.3 Configure OIDC endpoints

The issuer typically looks like:

• https://login.microsoftonline.com/{tenant-id}/v2.0

Retool may auto-discover OIDC endpoints via:

• https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

7.4 Configure OIDC in Retool

In Retool admin:

1. Enable OIDC SSO.
2. Enter:
   • Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0
   • Client ID: from Azure app registration.
   • Client Secret: you created earlier.
   • Scopes: include openid, profile, email (and offline_access if needed).
3. Map claims:
   • Email: preferred_username or email (depending on your configuration).
   • Name: name
   • Groups: groups (if using group claims and you’ve configured them in Azure AD).

Save, then test login with a user assigned to the app via Enterprise applications (Azure will create an Enterprise app for the registered app automatically).

---

8. Best Practices for Retool SSO with Okta or Azure AD

To make the most of SSO (SAML/OIDC) with Okta or Azure AD in Retool:

• Enforce SSO only (no local passwords)
  Once migrated and tested, limit login methods to SSO for consistency and better security.
• Use groups for RBAC and data-level permissions
  Retool supports flexible, granular permissions. Map IdP groups to:
  • Admin vs editor vs viewer roles
  • Environment access (prod vs staging)
  • Row-level or column-level access where applicable.
• Enable MFA and conditional access at the IdP
  Let Okta or Azure AD enforce MFA, trusted locations, device compliance, etc.
• Use separate apps for different environments (if needed)
  For complex organizations, using separate SSO apps per Retool environment (e.g. staging vs prod) can simplify access control and audit requirements.
• Monitor audit logs and usage analytics in Retool
  Retool supports audit logs and usage analytics to track:
  • Queries run against databases/APIs
  • User actions in Retool
  • App usage by team or role
• Review security documentation
  For detailed security posture, deployment options (cloud vs self-hosted), and compliance, consult Retool’s official security documentation.

---

9. Troubleshooting Common SSO Issues

If you run into problems configuring Retool SSO (SAML/OIDC) with Okta or Azure AD:

• “Invalid SAML response” or “Audience mismatch”
  • Ensure the Entity ID / Audience URI in your IdP matches what Retool expects.
  • Check ACS URL vs Reply URL.
• User can’t log in / unauthorized
  • Confirm the user is assigned to the Okta/Azure app.
  • Verify group-based access rules in Retool.
• Incorrect email or name
  • Check Attribute/Claim mappings in Okta/Azure AD.
  • Confirm Retool is reading the correct attribute/claim names.
• Group mappings not working
  • Verify groups are being sent in the SAML assertion or OIDC token.
  • Use test tools in Okta/Azure to inspect tokens or SAML responses.
  • Ensure the group names/IDs in Retool mapping match exactly.

For production deployments, test with multiple users and groups, and document your SSO configuration so future changes to Okta or Azure AD do not break Retool access.

---

Configuring Retool SSO (SAML/OIDC) with Okta or Azure AD gives you a secure, centralized authentication flow, while Retool’s RBAC and data-level permissions help ensure each user has exactly the access they need. Once SSO is in place, you can confidently scale internal tools across teams, departments, and external partners while maintaining strong security and compliance.