Setting Up SSO in Metabase: SAML, LDAP, and JWT

Single sign-on (SSO) in Metabase allows users to authenticate using their existing identity provider — Okta, Azure AD, Google Workspace, or any SAML 2.0-compatible provider — instead of maintaining a separate Metabase username and password. Metabase supports three SSO protocols: SAML 2.0 for enterprise identity providers, LDAP for directory-based authentication, and JWT for embedding scenarios where a parent application passes authenticated user identity into Metabase. All three are available in Metabase Pro and Enterprise.

---

Choosing the Right SSO Method

---

SAML 2.0 Configuration

SAML 2.0 is a federated identity protocol where your identity provider (Okta, Azure AD, etc.) acts as the source of truth for user identity, and Metabase trusts assertions it receives from that provider.

How SAML Works with Metabase

User visits Metabase
│ ▼ Metabase redirects to IdP login page │ ▼ User authenticates with IdP (password, MFA, etc.) │ ▼ IdP sends SAML assertion to Metabase (contains: email, name, group memberships) │ ▼ Metabase creates/updates user session │ ▼ User lands on Metabase dashboard

Step 1: Configure Metabase as a SAML Service Provider

In Metabase, navigate to Admin → Settings → Authentication → SAML.

Metabase provides:

• SAML Consumer URL (ACS URL): https://your-metabase.com/auth/sso

You'll need these values to configure your IdP.

Step 2: Configure Your Identity Provider

Okta:

- Single sign-on URL: https://your-metabase.com/auth/sso - Audience URI (SP Entity ID): https://your-metabase.com - Name ID format: EmailAddress - Application username: Email

- http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress → user.email - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname → user.firstName - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname → user.lastName

- Name: groups - Filter: Matches regex .* (or filter to specific groups)

Azure Active Directory:

- Identifier (Entity ID): https://your-metabase.com - Reply URL (ACS URL): https://your-metabase.com/auth/sso

- emailaddress: user.mail - firstname: user.givenname - lastname: user.surname

Google Workspace:

- ACS URL: https://your-metabase.com/auth/sso - Entity ID: https://your-metabase.com - Name ID format: EMAIL

- First name → firstName - Last name → lastName

Step 3: Configure Metabase SAML Settings

Back in Metabase Admin → Settings → Authentication → SAML:

Step 4: Configure Group Sync (Optional but Recommended)

SAML group sync automatically assigns Metabase permission groups based on groups from your IdP:

When a user logs in via SAML, Metabase updates their group membership based on the groups attribute in the SAML assertion.

Step 5: Test and Enable

Keep password-based login enabled until SAML is verified working, then optionally disable it.

---

LDAP Configuration

LDAP authentication connects Metabase directly to an LDAP or Active Directory server. Users log in with their directory credentials.

How LDAP Works with Metabase

Metabase binds to the LDAP server using a service account, searches for the user's DN based on their email/username, and attempts to bind as that user with the provided password. If the bind succeeds, the user is authenticated.

Configuration

Navigate to Admin → Settings → Authentication → LDAP.

LDAP Host: dc01.company.local
LDAP Port: 636 LDAP Security: SSL Bind DN: CN=Metabase Service,OU=Service Accounts,DC=company,DC=local User Search Base: OU=Users,DC=company,DC=local User Filter: (&(objectClass=user)(userPrincipalName={login}))

Attribute Mapping

Tell Metabase which LDAP attributes contain the user's name and email:

Group Sync with LDAP

Group Search Base: OU=Groups,DC=company,DC=local
Group Membership Filter: (member={dn})

Metabase will sync group membership from LDAP, mapping LDAP groups to Metabase permission groups in Admin → People → Groups → Group Mapping.

---

JWT SSO Configuration

JWT SSO is distinct from JWT embedding. While JWT embedding controls what a specific embedded dashboard shows, JWT SSO authenticates users into the full Metabase interface — and is the mechanism used to pass user attributes (like organization_id) that data sandbox policies reference.

How JWT SSO Works

User authenticates in your host application
│ ▼ Your server generates a JWT: { email: user.email, first_name: user.firstName, last_name: user.lastName, groups: ["Analytics Users"], organization_id: "99",   ← user attribute for sandboxing exp: now + 600 } Signed with MB_JWT_SHARED_SECRET │ ▼ Redirect user to: /auth/sso?jwt=<token>&return_to=/dashboard/42 │ ▼ Metabase validates token, creates session, sets user attributes, syncs groups │ ▼ User is logged in with correct permissions and sandbox attributes

Configuration

In Metabase: Admin → Settings → Authentication → JWT

bash
MB_JWT_SHARED_SECRET=your-long-random-shared-secret

Generating JWT SSO Tokens

javascript
// server-side only — never expose the secret client-side const jwt = require("jsonwebtoken"); 
function generateSsoToken(user) { const payload = { email: user.email, first_name: user.firstName, last_name: user.lastName, groups: user.metabaseGroups,          // e.g., ["Analytics Team"] 
// User attributes — referenced by sandbox policies organization_id: String(user.orgId), // must be strings role: user.role, 
exp: Math.round(Date.now() / 1000) + 600, // 10 min expiry }; 
return jwt.sign(payload, process.env.MB_JWT_SHARED_SECRET); } 
// Redirect user into Metabase with SSO function redirectToMetabase(res, user, returnTo = "/") { const token = generateSsoToken(user); const ssoUrl = ${process.env.METABASE_SITE_URL}/auth/sso?jwt=${token}&return_to=${encodeURIComponent(returnTo)}; res.redirect(ssoUrl); }

JWT SSO vs. JWT Embedding

These are two separate features that are often confused:

Google OAuth

For teams using Google Workspace who want simpler SSO without full SAML:

Admin → Settings → Authentication → Google Auth

Users will see a "Sign in with Google" button on the Metabase login page.

---

Security Best Practices for SSO

Enforce SSO — disable password login for non-admins

Once SSO is working, prevent users from bypassing it with passwords:

Require MFA at the IdP level

Metabase itself doesn't enforce MFA — that's the IdP's responsibility. Enforce MFA policies in Okta, Azure AD, or Google Workspace, and it applies automatically to Metabase users.

Audit SSO configuration changes

Changes to SSO configuration (especially SAML certificates) should go through your change management process. A misconfigured SAML certificate locks all SSO users out of Metabase.

Rotate certificates before expiry

SAML certificates from IdPs have expiry dates (typically 1–3 years). Add a calendar reminder to rotate the certificate in Metabase before it expires. An expired certificate causes all SAML logins to fail with a cryptic error.

Test SSO with a non-admin account

After configuring SSO, test with a standard (non-admin) user account in a private browser window. Admin accounts often bypass auth restrictions.

---

Troubleshooting SSO

"SAML response did not contain a valid signature" The IdP certificate in Metabase doesn't match what the IdP is using to sign assertions. Download a fresh certificate from your IdP and update Metabase.

"No user found with email X" Metabase can't create the user because auto-provisioning is disabled, or the email attribute in the SAML assertion doesn't match what Metabase expects. Check the attribute mapping in your IdP configuration.

Redirect loop on SSO login MB_SITE_URL is not set correctly in Metabase. The redirect URL in the SAML response must match the domain in MB_SITE_URL.

LDAP: "Invalid credentials" The bind DN or password is incorrect. Test the bind directly with ldapsearch:

bash
ldapsearch -H ldaps://ldap.yourcompany.com \ -D "cn=metabase,ou=services,dc=company,dc=com" \ -w your-password \ -b "ou=users,dc=company,dc=com" \ "(mail=testuser@company.com)"

JWT: "Token is expired" JWT tokens have a short expiry. Generate a fresh token immediately before redirecting the user.

---

Summary

Metabase supports SAML 2.0 (for enterprise IdPs like Okta and Azure AD), LDAP (for Active Directory environments), JWT SSO (for applications that manage their own authentication and need to pass user attributes for sandboxing), and Google OAuth (for Google Workspace teams). All require Metabase Pro or Enterprise. SAML is the right choice for most enterprise deployments. JWT SSO is required when user attributes need to be passed into Metabase for data sandbox policies. Configure group sync in all cases to automate permission management — manually assigning users to groups at scale is not maintainable.