Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs: JWT, SAML, LDAP and OIDC redesign (#85962)

Michael Eby97ace2642786
diff --git a/docs/people-and-groups/authenticating-with-jwt.md b/docs/people-and-groups/authenticating-with-jwt.md
index 2d71d8f8e97..e023e0c283a 100644
--- a/docs/people-and-groups/authenticating-with-jwt.md
+++ b/docs/people-and-groups/authenticating-with-jwt.md
@@ -56,7 +56,7 @@ Here's a breakdown of each of the settings:
- **String used by the JWT signing key**: The string used to seed the private key used to validate JWT messages. Both Metabase and your authentication app must use the same key. Click **Set up key**, then generate a key or paste your own.
-The **User provisioning**, **User attribute configuration**, and **Group mapping** sections are disabled until you save your settings.
+Until you save your settings, the **User attribute configuration** and **Group mapping** sections stay locked. You can edit **User provisioning** before you save.
## User attribute configuration (optional)
@@ -82,12 +82,14 @@ To add groups to your JWT, use the syntax `groups: ["group_name"]`, where `group
The **Group mapping** section has three options:
-- **Automatic**: If a person's JWT contains group names that match Metabase groups, Metabase will add the person to those Metabase groups.
+- **Automatic**: At each sign-in, Metabase adds people to the Metabase groups named in their JWT and removes them from all other groups, including Administrators.
- **Manual**: Metabase adds people to groups using only the mappings you create.
- **Off**: Metabase ignores your saved mappings and doesn't add people to groups.
When you first set up JWT, Metabase sets the group mapping to **Automatic**.
+In **Automatic** mode, Metabase changes group membership only when the JWT includes the group attribute. If the attribute is missing, memberships stay as they are. Metabase never removes the last remaining admin, and never changes All Users membership.
+
To create manual mappings:
1. Select **Manual**.
@@ -101,19 +103,23 @@ Metabase saves each mapping as soon as you add, edit, or remove the mapping.
![JWT group mappings](./images/jwt-groups.png)
-To edit or remove a mapping, hover over the mapping and click the pencil or trash icon.
+To edit a mapping, hover over the mapping and click the pencil icon.
Switching from **Manual** to **Automatic** deletes all of your mappings. Removing your last mapping switches group mapping to **Off**.
#### Remove a group mapping
-To remove a mapping, hover over the mapping and click the trash icon. Choose what to do with the groups in the mapping:
+To remove a mapping, hover over the mapping and click the trash icon. Metabase asks what should happen to the Metabase group:
- **Nothing, just remove the mapping**
-- **Also remove all members from this group** (Metabase keeps their accounts)
-- **Also delete the group** (the Administrators group isn't affected)
+- **Also remove all members from this group**. Members keep their Metabase accounts.
+- **Also delete the group**
+
+Then click **Remove mapping**. Removing members or deleting a group takes effect immediately and can't be undone.
+
+If the mapping points to a built-in group such as Administrators, Metabase doesn't offer these options. It removes the mapping without changing the group or its members.
-Removing members or deleting groups takes effect immediately and can't be undone!
+**Also delete the group** isn't available when another mapping uses the same Metabase group.
### Configure group mapping through environment variables
@@ -121,7 +127,7 @@ You can use the following environment variables to configure JWT group mappings
- [`MB_JWT_ATTRIBUTE_GROUPS`](../configuring-metabase/environment-variables.md#mb_jwt_attribute_groups) to specify the key to retrieve the JWT user's groups;
-- [`MB_JWT_GROUP_SYNC`](../configuring-metabase/environment-variables.md#mb_jwt_group_sync) to turn group sync on or off (sync is off by default).
+- [`MB_JWT_GROUP_SYNC`](../configuring-metabase/environment-variables.md#mb_jwt_group_sync) to turn group sync on or off. The setting is off by default. If you don't set this variable, saving the JWT settings page for the first time turns group sync on in **Automatic** mode.
```
MB_JWT_GROUP_SYNC=true
@@ -143,7 +149,7 @@ If you set either `MB_JWT_GROUP_SYNC` or `MB_JWT_GROUP_MAPPINGS`, the **Group ma
> Paid plans [charge for each additional account](https://www.metabase.com/how-billing-works#what-counts-as-a-user-account).
-User provisioning is enabled by default. When someone logs in via JWT SSO, Metabase creates an account for them if they don't have one, and reactivates their account if it is deactivated.
+User provisioning is enabled by default. When someone logs in via JWT SSO, Metabase creates an account for them if they don't have one, and reactivates their account if it is deactivated. The switch saves on its own, so you don't need to click **Save and enable** after you change it.
If you disable user provisioning, users without accounts or with deactivated accounts will not be able to log in via JWT SSO.
diff --git a/docs/people-and-groups/authenticating-with-oidc.md b/docs/people-and-groups/authenticating-with-oidc.md
index 44cb9703fcb..40f6fce89a7 100644
--- a/docs/people-and-groups/authenticating-with-oidc.md
+++ b/docs/people-and-groups/authenticating-with-oidc.md
@@ -12,7 +12,7 @@ By integrating your OpenID Connect (OIDC) provider with Metabase, you can:
- [Provision a Metabase account](#user-provisioning) when someone logs in via your identity provider (IdP).
- Let people access Metabase without re-authenticating.
- Automatically pass user attributes (name, email) from your IdP to Metabase.
-- [Synchronize group membership](#synchronize-group-membership) so that people are automatically assigned to Metabase groups based on their IdP groups.
+- [Map IdP groups to Metabase groups](#group-mapping) so that people are automatically assigned when they log in.
## Self-hosted Metabases must set an encryption key
@@ -36,7 +36,9 @@ _Admin > Settings > Authentication > OIDC_
You can also configure OIDC with [environment variables](#environment-variables).
-You'll need to enter the following:
+Fill out **Server settings**, then click **Save and enable**. Until you save, the **Group mapping** section stays locked. You can edit **User provisioning** and **Attributes** before you save.
+
+Every field except **Scopes** is required.
| Field | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -44,49 +46,68 @@ You'll need to enter the following:
| **Login prompt** | The button label on Metabase's sign-in screen. You can put something like "Sign in with Keycloak", or "Ye who wish to enter Metabase". |
| **Issuer URI** | Your IdP's issuer URI. Metabase fetches the discovery document from `{issuer-uri}/.well-known/openid-configuration`. This request is made from Metabase's server, not from the browser. In containerized deployments (like Docker), the URI must be reachable from Metabase's container, not just from your browser. |
| **Client ID** | The Client ID assigned for Metabase in your OIDC provider. |
-| **Client Secret** | The client secret from your OIDC provider. When editing an existing configuration, leave this blank to keep the current value. |
-
-### Optional settings
-
-**Scopes**: The OIDC scopes to request. In the admin UI, enter scopes as a comma-separated string (e.g., `openid, email, profile`). Defaults to `openid, email, profile`. Most providers don't require changes here. If you're setting this with the `MB_OIDC_PROVIDERS` environment variable JSON, use an array (e.g., `["openid", "email", "profile"]`).
+| **Client secret** | The client secret from your OIDC provider. When editing an existing configuration, leave this blank to keep the current value. |
+| **Scopes** (optional) | The OIDC scopes to request. Enter them as a comma-separated string, for example `openid, email, profile`. Defaults to `openid, email, profile`. Most providers don't require changes here. If you're setting this with the `MB_OIDC_PROVIDERS` environment variable, use an array, for example `["openid", "email", "profile"]`. |
-### Attribute mapping
+### Attributes
Metabase maps OIDC claims to account fields. The defaults work for most providers:
-| Metabase field | Default claim |
-| -------------- | ------------- |
-| Email | `email` |
-| First name | `given_name` |
-| Last name | `family_name` |
+| Metabase field | Default claim |
+| -------------- | -------------------------- |
+| Email | `email` (can't be changed) |
+| First name | `given_name` |
+| Last name | `family_name` |
-If your IdP uses different claim names, update these fields to match.
+If your IdP uses different claim names, update the first and last name fields to match. A blank claim name counts as unset, so Metabase falls back to the default.
-## Synchronize group membership
+If you configure OIDC with the [`MB_OIDC_PROVIDERS`](#environment-variables) environment variable, Metabase ignores an `email` entry in `attribute-map` rather than reporting an error.
+
+## Group mapping
You can configure Metabase to automatically sync group memberships from your IdP, so that people are added to (or removed from) Metabase groups based on their IdP groups.
OIDC doesn't define a standard groups claim. You'll need to configure your IdP to include a groups claim in the ID token. Some IdPs (like Azure AD/Entra ID) require a specific `groups` scope or API permission to include group claims — check your provider's docs. Keycloak includes groups via a client scope mapper without needing an extra scope. For a Keycloak example, see [Sync groups from Keycloak to Metabase](./oidc-keycloak.md#sync-groups-from-keycloak-to-metabase).
-### Configure group sync in Metabase
+### Configure group mapping in Metabase
-> If your provider is configured via the `MB_OIDC_PROVIDERS` environment variable, group sync settings are read-only in the admin UI. Manage group mappings in the environment variable instead. See [Environment variables](#environment-variables).
+> If your provider is configured via the `MB_OIDC_PROVIDERS` environment variable, group mapping settings are read-only in the admin UI. Manage group mappings in the environment variable instead. See [Environment variables](#environment-variables).
1. Go to **Admin** > **Settings** > **Authentication** > **OIDC** and select your provider.
-2. Turn on **Synchronize Group Memberships**. You can click **About mappings** to learn more about how group mappings work.
-3. Click **New mapping** and enter the group name exactly as your IdP sends it (case-sensitive).
-4. Select one or more Metabase groups to map it to.
-5. Repeat for each group you want to map.
-6. Set the **Group attribute name** to the claim name your IdP uses for groups (defaults to `groups`). This must match the claim name in the ID token exactly.
-7. Click **Save**.
+2. In the **Group mapping** section, turn on the toggle.
+3. Next to **Manual group mappings**, click **New**.
+4. Enter the group name exactly as your IdP sends it (case-sensitive).
+5. Select the Metabase groups to map the group name to.
+6. Click **Add mapping**.
+7. Repeat steps 3 to 6 for each group you want to map.
+8. In **Group attribute name**, enter the OIDC claim that contains group membership information. Defaults to `groups`. This must match the claim name in the ID token exactly.
+9. Click **Save and enable**.
+
+Metabase saves each mapping as soon as you add, edit, or remove the mapping. To edit a mapping, hover over the mapping and click the pencil icon.
+
+![OIDC group mapping](images/oidc-group-mapping.png)
-### How group sync works
+### How group mapping works
- Metabase updates group memberships on each login based on the groups claim in the ID token.
- If a person's groups claim no longer includes a mapped group, Metabase removes them from the corresponding Metabase group.
-- Only mapped groups are affected. Memberships in unmapped Metabase groups (including Admin) aren't changed.
+- Only mapped groups are affected. Memberships in unmapped Metabase groups (including Administrators) aren't changed.
- If the groups claim is missing from the token entirely, Metabase leaves existing group memberships unchanged.
+### Remove a group mapping
+
+To remove a mapping, hover over the mapping and click the trash icon. Metabase asks what should happen to the Metabase group:
+
+- **Nothing, just remove the mapping**
+- **Also remove all members from this group**. Members keep their Metabase accounts.
+- **Also delete the group**
+
+Then click **Remove mapping**. Removing members or deleting a group takes effect immediately and can't be undone.
+
+If the mapping points to a built-in group such as Administrators, Metabase doesn't offer these options. It removes the mapping without changing the group or its members.
+
+**Also delete the group** isn't available when another mapping uses the same Metabase group.
+
## Check connection
After entering your OIDC provider settings in **Admin** > **Settings** > **Authentication** > **OIDC**, click **Check connection** to verify that Metabase can reach your provider. The check verifies two things: 1) that Metabase can fetch the discovery document from your Issuer URI, and 2) that the client credentials are valid.
@@ -97,7 +118,7 @@ If the check reports "OIDC discovery succeeded, but credentials could not be ver
By default, Metabase creates accounts for people who authenticate successfully via OIDC but don't yet have a Metabase account. Metabase uses the email claim to identify and create accounts, so the `email` scope must be included in what your IdP returns.
-You can turn auto-provisioning off under **Admin settings** > **Authentication** > **OIDC** > **User provisioning**. If you've set up [User provisioning with SCIM](./user-provisioning.md), turn off automatic account creation to avoid conflicts.
+You can turn auto-provisioning off under **Admin** > **Settings** > **Authentication** > **OIDC** > **User provisioning**. The switch saves on its own, so you don't need to click **Save and enable** after you change it. If you've set up [User provisioning with SCIM](./user-provisioning.md), turn off automatic account creation to avoid conflicts.
### How auto-provisioning works
@@ -113,48 +134,47 @@ You can also configure OIDC via environment variables instead of the admin UI. S
- [`MB_OIDC_USER_PROVISIONING_ENABLED`](../configuring-metabase/environment-variables.md#mb_oidc_user_provisioning_enabled): toggle auto-provisioning (`true` by default).
- [`MB_OIDC_PROVIDERS`](../configuring-metabase/environment-variables.md#mb_oidc_providers): JSON string containing the full provider configuration. The value is an array of provider objects. Here's an example:
- ```json
- [
- {
- "key": "keycloak",
- "login-prompt": "Sign in with Keycloak",
- "issuer-uri": "http://keycloak:8080/realms/metabase",
- "client-id": "metabase-client",
- "client-secret": "metabase-client-secret",
- "scopes": ["openid", "email", "profile"],
- "enabled": true,
- "attribute-map": {
- "email": "email",
- "first_name": "given_name",
- "last_name": "family_name"
- },
- "group-sync": {
- "enabled": true,
- "group-attribute": "groups",
- "group-mappings": {
- "engineering": [5, 6],
- "data-team": [3]
- }
- }
- }
- ]
- ```
-
- | Field | Required | Default |
- | ------------------------------ | -------- | -------------------------------- |
- | **key** | Yes | |
- | **login-prompt** | Yes | |
- | **issuer-uri** | Yes | |
- | **client-id** | Yes | |
- | **client-secret** | Yes | |
- | **enabled** | No | `true` |
- | **scopes** | No | `["openid", "email", "profile"]` |
- | **attribute-map** | No | See attribute map above |
- | **group-sync.enabled** | No | `false` |
- | **group-sync.group-attribute** | No | `"groups"` |
- | **group-sync.group-mappings** | No | `{}` |
-
- The `group-sync` fields are nested inside each provider object. In `group-mappings`, keys are IdP group names and values are arrays of Metabase group IDs. You can find group IDs under **Admin** > **People** > **Groups**, or via the `GET /api/permissions/group` API endpoint.
+ ```json
+ [
+ {
+ "key": "keycloak",
+ "login-prompt": "Sign in with Keycloak",
+ "issuer-uri": "http://keycloak:8080/realms/metabase",
+ "client-id": "metabase-client",
+ "client-secret": "metabase-client-secret",
+ "scopes": ["openid", "email", "profile"],
+ "enabled": true,
+ "attribute-map": {
+ "first_name": "given_name",
+ "last_name": "family_name"
+ },
+ "group-sync": {
+ "enabled": true,
+ "group-attribute": "groups",
+ "group-mappings": {
+ "engineering": [5, 6],
+ "data-team": [3]
+ }
+ }
+ }
+ ]
+ ```
+
+ | Field | Required | Default |
+ | ------------------------------ | -------- | -------------------------------- |
+ | **key** | Yes | |
+ | **login-prompt** | Yes | |
+ | **issuer-uri** | Yes | |
+ | **client-id** | Yes | |
+ | **client-secret** | Yes | |
+ | **enabled** | No | `true` |
+ | **scopes** | No | `["openid", "email", "profile"]` |
+ | **attribute-map** | No | See attribute map above |
+ | **group-sync.enabled** | No | `false` |
+ | **group-sync.group-attribute** | No | `"groups"` |
+ | **group-sync.group-mappings** | No | `{}` |
+
+ The `group-sync` fields are nested inside each provider object. In `group-mappings`, keys are IdP group names and values are arrays of Metabase group IDs. You can find group IDs under **Admin** > **People** > **Groups**, or via the `GET /api/permissions/group` API endpoint.
See [Environment variables](../configuring-metabase/environment-variables.md).
@@ -162,7 +182,7 @@ See [Environment variables](../configuring-metabase/environment-variables.md).
> **Avoid locking yourself out.** Disabling password logins applies to all accounts, including your Metabase admin account. Before doing this, verify that you can log in with SSO.
-To require SSO for all logins, go to **Admin settings** > **Authentication** and turn off **Enable Password Authentication**.
+To require SSO for all logins, go to **Admin** > **Settings** > **Authentication** > **Overview** and turn off **Enable password authentication**.
## OIDC example provider guide
diff --git a/docs/people-and-groups/authenticating-with-saml.md b/docs/people-and-groups/authenticating-with-saml.md
index 1db28e6851c..b5fef1bac74 100644
--- a/docs/people-and-groups/authenticating-with-saml.md
+++ b/docs/people-and-groups/authenticating-with-saml.md
@@ -24,10 +24,10 @@ After you [confirm the password for your Metabase admin account](#confirm-the-pa
The form includes the following sections:
-1. [Configure your identity provider (IdP)](#generic-saml-configuration)
-2. [Tell Metabase about your identity provider](#enabling-saml-authentication-in-metabase)
+1. [Identity provider (IdP) configuration](#identity-provider-idp-configuration)
+2. [Identity provider info](#identity-provider-info)
3. [User provisioning](#user-provisioning)
-4. [Signing SSO requests (optional)](#settings-for-signing-sso-requests-optional)
+4. [Sign SSO requests](#sign-sso-requests)
5. [Group mapping](#group-mapping)
## SAML guides
@@ -46,17 +46,17 @@ If you don't see your IdP listed here:
- Refer to your IdP's reference docs on configuring SAML. You'll be looking for something like this [OneLogin SAML guide](https://onelogin.service-now.com/support?id=kb_article&sys_id=83f71bc3db1e9f0024c780c74b961970).
- Using the information found on the Metabase SAML form, fill out your IdP's SAML form.
-- For more information, see the next section on [Generic SAML configuration](#generic-saml-configuration).
+- For more information, see the next section on [Identity provider (IdP) configuration](#identity-provider-idp-configuration).
## User provisioning
-User provisioning is enabled by default. Metabase will create accounts for people who don't yet have a Metabase account but who are able to log in via SAML SSO.
+User provisioning is enabled by default. When someone logs in via SAML SSO, Metabase creates an account for them if they don't have one, and reactivates their account if it is deactivated. The switch saves on its own, so you don't need to click **Save and enable** after you change it.
If you disable user provisioning, users without accounts or with deactivated accounts will not be able to log in.
If you manage user provisioning with [SCIM](./user-provisioning.md), you can't turn on SAML user provisioning.
-## Generic SAML configuration
+## Identity provider (IdP) configuration
The top portion of the SAML form in Metabase has the information you'll need to fill out your IdP's SAML form, with buttons to make copying the information easy.
@@ -88,11 +88,11 @@ Metabase will automatically log in people who've been authenticated by your SAML
Most IdPs already include these assertions by default, but some (such as [Okta](./saml-okta.md)) must be configured to include them.
-Generally you'll need to paste these user attributes (first name, last name, and email) into fields labelled "Name", "Attributes" or "Parameters".
+Metabase shows the values for **User's email attribute**, **User's first name attribute**, and **User's last name attribute**. Copy each one into an input box labeled "Name" in your IdP's attribute statements section.
> If you allow people to edit their email addresses: make sure to update the corresponding account emails in Metabase. Keeping email addresses in sync will protect people from losing access to their accounts.
-## Enabling SAML authentication in Metabase
+## Identity provider info
Metabase will now need to know some things about your IdP. Here's a breakdown of each of the settings:
@@ -136,7 +136,7 @@ The SAML identity provider issuer is a required unique identifier for the IdP. Y
| [Okta](saml-okta.md) | Identity Provider Issuer |
| OneLogin | Issuer URL |
-### Settings for signing SSO requests (optional)
+### Sign SSO requests
To sign requests so that they can't be tampered with, you'll need to provide additional settings.
@@ -176,31 +176,38 @@ Group mapping lets you assign people to Metabase groups based on an attribute of
First, you will need to create a SAML user attribute that you will use to indicate which Metabase groups the person should be a part of. This created user attribute can be an XML string or a list of XML strings. Different IdPs have different ways of handling this, but you will likely need to edit your user profiles or find a way to map a user's groups to a list of Metabase group names.
-## Configuring the group schema in Metabase
+## Configuring group mappings in Metabase
After you set up the group attribute in your IdP, configure group mappings:
-1. In the **Group mapping** section, enable the **Synchronize Group Memberships** toggle.
-2. Click **New mapping**.
-3. In the **Group name** field, enter one of the values from your `metabaseGroups` attribute, then click **Add**.
+1. In the **Group mapping** section, turn on the toggle.
+2. Next to **Manual group mappings**, click **New**.
+3. Enter one of the values from your `metabaseGroups` attribute.
4. Select the Metabase groups that people with this value should be added to.
-5. Repeat steps 2 to 4 for each group you want to map.
-6. In **Group attribute name**, enter the name of the SAML attribute that contains the group names. For example, if you named the attribute `MetabaseGroupName` in Okta, enter `MetabaseGroupName`.
-7. Click **Save and enable**.
+5. Click **Add mapping**.
+6. Repeat steps 2 to 5 for each group you want to map.
+7. In **Group attribute name**, enter the name of the SAML attribute that contains the group names. For example, if you named the attribute `MetabaseGroupName` in Okta, enter `MetabaseGroupName`.
+8. Click **Save and enable**.
-Metabase saves each mapping as soon as you add, edit, or remove it. The **Synchronize Group Memberships** toggle and the **Group attribute name** field save only when you click **Save and enable**.
+**Group attribute name** is required. Until you set it, Metabase assigns no groups.
-![Group schema](images/saml-okta-groups.png)
+Metabase saves each mapping as soon as you add, edit, or remove it. To edit a mapping, hover over it and click the pencil icon.
+
+![Group mapping](images/saml-okta-groups.png)
### Remove a group mapping
-To remove a mapping, click the **X** next to it. Choose what to do with the groups in the mapping:
+To remove a mapping, hover over it and click the trash icon. Metabase asks what should happen to the Metabase group:
- **Nothing, just remove the mapping**
-- **Also remove all members from this group** (Metabase keeps their accounts)
-- **Also delete the group** (the Administrators group isn't affected)
+- **Also remove all members from this group**. Members keep their Metabase accounts.
+- **Also delete the group**
+
+Then click **Remove mapping**. Removing members or deleting a group takes effect immediately and can't be undone.
+
+If the mapping points to a built-in group such as Administrators, Metabase doesn't offer these options. It removes the mapping without changing the group or its members.
-Removing members or deleting groups takes effect immediately and can't be undone.
+**Also delete the group** isn't available when another mapping uses the same Metabase group.
## Creating Metabase accounts with SSO
diff --git a/docs/people-and-groups/images/ldap-group-mapping.png b/docs/people-and-groups/images/ldap-group-mapping.png
index 228c06c03c6..a22c558d37d 100644
Binary files a/docs/people-and-groups/images/ldap-group-mapping.png and b/docs/people-and-groups/images/ldap-group-mapping.png differ
diff --git a/docs/people-and-groups/images/oidc-group-mapping.png b/docs/people-and-groups/images/oidc-group-mapping.png
new file mode 100644
index 00000000000..5cd1595ae2d
Binary files /dev/null and b/docs/people-and-groups/images/oidc-group-mapping.png differ
diff --git a/docs/people-and-groups/images/saml-okta-groups.png b/docs/people-and-groups/images/saml-okta-groups.png
index 4ddac56b4af..09e2162f6e6 100644
Binary files a/docs/people-and-groups/images/saml-okta-groups.png and b/docs/people-and-groups/images/saml-okta-groups.png differ
diff --git a/docs/people-and-groups/ldap.md b/docs/people-and-groups/ldap.md
index d3fcb9ea33d..ca2d6d9c014 100644
--- a/docs/people-and-groups/ldap.md
+++ b/docs/people-and-groups/ldap.md
@@ -24,11 +24,7 @@ Your LDAP directory must have the email field populated for each entry that will
To enable LDAP authentication, go to **Admin** > **Settings** > **Authentication** > **LDAP** and click **Set up**. Fill out the form, then click **Save and enable**.
-## User provisioning
-
-User provisioning is enabled by default. When someone logs in via LDAP, Metabase creates an account for them if they don't have one, and reactivates their account if it is deactivated.
-
-If you disable user provisioning, users without accounts or with deactivated accounts will not be able to log in.
+Until you save your server settings, the **Attributes** and **Group mapping** sections stay locked. You can edit **User provisioning** before you save.
## Server settings
@@ -40,6 +36,12 @@ If you disable user provisioning, users without accounts or with deactivated acc
Then save your changes. Metabase will automatically pull the [required attributes](#required-ldap-attributes) from your LDAP directory.
+## User provisioning
+
+User provisioning is enabled by default. When someone logs in via LDAP, Metabase creates an account for them if they don't have one, and reactivates their account if it is deactivated. The switch saves on its own, so you don't need to click **Save changes** after you change it.
+
+If you disable user provisioning, users without accounts or with deactivated accounts will not be able to log in.
+
## User schema
The **User schema** section on this same page is where you can adjust settings related to where and how Metabase connects to your LDAP server to authenticate users.
@@ -75,21 +77,37 @@ To map an LDAP group to a Metabase group:
5. Click **Add mapping**.
6. Repeat steps 2 to 5 for each group you want to map.
+Metabase saves each mapping as soon as you add, edit, or remove it. To edit a mapping, hover over it and click the pencil icon.
+
Some LDAP directories list each person's groups on their own entry. If yours does, leave **Group search base** empty. Otherwise, enter the DN where your group entries live.
![Group Mapping](images/ldap-group-mapping.png)
Some things to keep in mind regarding group mapping:
-- The Administrators group works like any other group.
+- Metabase syncs membership of the Administrators group like any other group.
- Updates to a person's group membership based on LDAP mappings are not instantaneous; the changes will take effect only _after_ people log back in.
- People are only ever added to or removed from mapped groups. The sync has no effect on Metabase groups that don't have an LDAP mapping.
-## LDAP group membership filter
+### Remove a group mapping
+
+To remove a mapping, hover over it and click the trash icon. Metabase asks what should happen to the Metabase group:
+
+- **Nothing, just remove the mapping**
+- **Also remove all members from this group**. Members keep their Metabase accounts.
+- **Also delete the group**
+
+Then click **Remove mapping**. Removing members or deleting a group takes effect immediately and can't be undone.
+
+If the mapping points to a built-in group such as Administrators, Metabase doesn't offer these options. It removes the mapping without changing the group or its members.
+
+**Also delete the group** isn't available when another mapping uses the same Metabase group.
+
+### Group membership filter
{% include plans-blockquote.html feature="LDAP advanced features" is_plural=true %}
-Group membership lookup filter. The placeholders {dn} and {uid} will be replaced by the user's Distinguished Name and UID, respectively.
+If your directory doesn't list each person's groups on their own entry, Metabase looks up membership on the group entries instead. **Group membership filter** sets that lookup filter. Metabase replaces the placeholders `{dn}` and `{uid}` with the person's distinguished name and UID.
## Syncing user attributes with LDAP
diff --git a/docs/people-and-groups/oidc-keycloak.md b/docs/people-and-groups/oidc-keycloak.md
index 214f8d06840..e67f62411e0 100644
--- a/docs/people-and-groups/oidc-keycloak.md
+++ b/docs/people-and-groups/oidc-keycloak.md
@@ -81,7 +81,7 @@ Check the [Keycloak event log](https://www.keycloak.org/docs/latest/server_admin
## Map attributes from Keycloak to Metabase
-Keycloak's default OIDC claims (`email`, `given_name`, `family_name`) match Metabase's defaults, so no extra configuration is needed. See [Attribute mapping](./authenticating-with-oidc.md#attribute-mapping).
+Keycloak's default OIDC claims (`email`, `given_name`, `family_name`) match Metabase's defaults, so no extra configuration is needed. See [Attributes](./authenticating-with-oidc.md#attributes).
## Sync groups from Keycloak to Metabase
@@ -100,9 +100,9 @@ You can configure Keycloak to include a groups claim in the OIDC token, then set
- **Add to ID token**: On.
6. Click **Save**.
-### Configure group sync in Metabase
+### Configure group mapping in Metabase
-Once Keycloak includes the groups claim in the token, set up the mapping in Metabase. See [Configure group sync in Metabase](./authenticating-with-oidc.md#configure-group-sync-in-metabase) for the steps.
+Once Keycloak includes the groups claim in the token, set up the mapping in Metabase. See [Configure group mapping in Metabase](./authenticating-with-oidc.md#configure-group-mapping-in-metabase) for the steps.
## Verify the setup
diff --git a/docs/people-and-groups/saml-auth0.md b/docs/people-and-groups/saml-auth0.md
index 24fd6025c9f..3ab497ace62 100644
--- a/docs/people-and-groups/saml-auth0.md
+++ b/docs/people-and-groups/saml-auth0.md
@@ -9,7 +9,7 @@ redirect_from:
{% include plans-blockquote.html feature="SAML authentication" %}
1. [Configure SAML in Auth0](#working-in-the-auth0-console) (the identity provider).
-2. [Configure SAML in Metabase](./authenticating-with-saml.md#enabling-saml-authentication-in-metabase) (the service provider).
+2. [Configure SAML in Metabase](./authenticating-with-saml.md#setting-up-saml-with-your-idp-in-metabase) (the service provider).
For more information, check out our guide for [authenticating with SAML](./authenticating-with-saml.md).
@@ -28,7 +28,7 @@ Enter “Metabase” as the application name with type “Regular Web Applicatio
Now go to the Settings tab inside Auth0's Metabase App and fill in the following values:
- Application Login URI: the URL of your Metabase instance.
-- Allowed Callback URLs: the URL that's below **Configure your identity provider (IdP)** in SAML settings inside Metabase (it ends with `/auth/sso`).
+- Allowed Callback URLs: the URL that's below **Identity provider (IdP) configuration** in SAML settings inside Metabase (it ends with `/auth/sso`).
![Auth0 SAML Settings Page](images/auth0callbackurl.png)
@@ -69,11 +69,11 @@ Next, in the Auth0 Addon: SAML2 Web App popup, click on the **Usage** tab and th
| Metabase | Auth0 |
| ---------------------------------- | ------------------------------------------------------------------------------------------ |
-| SAML Identity Provider URL | Identity Provider Login URL |
-| SAML Identity Provider Issuer | Issuer |
-| SAML Identity Provider Certificate | Open the Identity Provider Metadata link and copy the string under the X509Certificate tag |
+| SAML identity provider URL | Identity Provider Login URL |
+| SAML identity provider issuer | Issuer |
+| SAML identity provider certificate | Open the Identity Provider Metadata link and copy the string under the X509Certificate tag |
-The "SAML Application Name" value can be left as the default (Metabase).
+The "SAML application name" value can be left as the default (Metabase).
Save your settings, then [enable SAML](authenticating-with-saml.md) in Metabase, and you should be good to go!
diff --git a/docs/people-and-groups/saml-google.md b/docs/people-and-groups/saml-google.md
index ffdb34d5bcc..c0f96a21367 100644
--- a/docs/people-and-groups/saml-google.md
+++ b/docs/people-and-groups/saml-google.md
@@ -64,7 +64,7 @@ For example, to add the attribute "First name":
1. In Google Admin, you can EITHER:
- Set up a multi-value [custom user attribute](https://knowledge.workspace.google.com/admin/users/create-custom-attributes-for-user-profiles) for your users. Recommended if you manage multiple SAML app permissions in Google or if you lack existing Google Groups that align with your desired Metabase groups.
- [Map to existing Google Groups](https://knowledge.workspace.google.com/admin/apps/about-group-membership-mapping).
-2. Follow the instructions for [Configuring the group schema](./authenticating-with-saml.md#configuring-the-group-schema-in-metabase) using the `App attribute` that you used in Google as the Group attribute name in Metabase.
+2. Follow the instructions for [Configuring group mappings](./authenticating-with-saml.md#configuring-group-mappings-in-metabase) using the `App attribute` that you used in Google as the Group attribute name in Metabase.
## Troubleshooting SAML issues
diff --git a/docs/people-and-groups/saml-keycloak.md b/docs/people-and-groups/saml-keycloak.md
index d1dbbdcb858..f3d2df9f221 100644
--- a/docs/people-and-groups/saml-keycloak.md
+++ b/docs/people-and-groups/saml-keycloak.md
@@ -9,7 +9,7 @@ redirect_from:
Keycloak is an open source platform that can be used as a user directory to save user data while acting as the IdP for single sign-on.
1. [Set up SAML in Keycloak](#working-in-the-keycloak-console) (the identity provider).
-2. [Set up SAML in Metabase](./authenticating-with-saml.md#enabling-saml-authentication-in-metabase) (the service provider).
+2. [Set up SAML in Metabase](./authenticating-with-saml.md#setting-up-saml-with-your-idp-in-metabase) (the service provider).
For more information, check out our guide for [authenticating with SAML](./authenticating-with-saml.md).
@@ -29,7 +29,7 @@ For more information, check out our guide for [authenticating with SAML](./authe
- **Home URL**: In your Metabase, go to **Admin** > **Settings** > **Authentication** > **SAML**. You'll find your Home URL in the field **URL the IdP should redirect back to**.
- Click **Save**.
-5. (Optional, but recommended on test environments) Disable key signing for SSO client. See [settings for signing SSO requests](./authenticating-with-saml.md#settings-for-signing-sso-requests-optional).
+5. (Optional, but recommended on test environments) Disable key signing for SSO client. See [settings for signing SSO requests](./authenticating-with-saml.md#sign-sso-requests).
- Click **Keys** tab.
- **Client signature required:** Off.
@@ -87,16 +87,17 @@ In your Keycloak client:
### Set up group mapping in Metabase
1. Go to **Admin** > **Settings** > **Authentication** > **SAML**.
-2. In the **Group mapping** section, enable the **Synchronize Group Memberships** toggle.
-3. Click **New mapping**.
-4. Enter the name of a Keycloak group, then click **Add**.
+2. In the **Group mapping** section, turn on the toggle.
+3. Next to **Manual group mappings**, click **New**.
+4. Enter the name of a Keycloak group.
Keycloak groups show up in Metabase with the slash character ("/") prepended to the group name. A group named `sales` in Keycloak shows up as `/sales`.
5. Select the Metabase groups to map the group name to.
-6. Repeat steps 3 to 5 for each group.
-7. In **Group attribute name**, enter `member_of` (the name for the attribute with the group list in your Keycloak configuration).
-8. Click **Save and enable**.
+6. Click **Add mapping**.
+7. Repeat steps 3 to 6 for each group.
+8. In **Group attribute name**, enter `member_of` (the name for the attribute with the group list in your Keycloak configuration).
+9. Click **Save and enable**.
## Troubleshooting SAML issues
diff --git a/docs/people-and-groups/saml-okta.md b/docs/people-and-groups/saml-okta.md
index 57096ce8e3f..d130799ef46 100644
--- a/docs/people-and-groups/saml-okta.md
+++ b/docs/people-and-groups/saml-okta.md
@@ -34,10 +34,10 @@ To configure Okta app integration with Metabase, you'll need to use the informat
#### General settings
-| Okta SAML | Metabase SAML |
-| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Single sign-on URL** | **URL the IdP should redirect to**. This is your Metabase [Site URL][site-url] -- it should start with `https://` and end with `/auth/sso`. |
-| **Audience URI (SP Entity ID)** | **SAML Application Name** ("Metabase" by default) |
+| Okta SAML | Metabase SAML |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Single sign-on URL** | **URL the IdP should redirect back to**. This is your Metabase [Site URL][site-url] -- it should start with `https://` and end with `/auth/sso`. |
+| **Audience URI (SP Entity ID)** | **SAML application name** ("Metabase" by default) |
#### Attribute statements
@@ -115,9 +115,9 @@ Use the information from Okta SAML instructions to fill the Metabase SAML form i
| Metabase SAML | Okta SAML |
| ---------------------------------- | ------------------------------------ |
-| SAML Identity Provider URL | Identity Provider Single Sign-On URL |
-| SAML Identity Provider Certificate | X.509 Certificate\* |
-| SAML Identity Provider Issuer | Identity Provider Issuer |
+| SAML identity provider URL | Identity Provider Single Sign-On URL |
+| SAML identity provider certificate | X.509 Certificate\* |
+| SAML identity provider issuer | Identity Provider Issuer |
\*Make sure to include any header and footer comments, like `---BEGIN CERTIFICATE---` and `---END CERTIFICATE---`.
@@ -152,15 +152,16 @@ You can create a custom user profile attribute and fill it with the Metabase gro
4. In **Metabase SAML settings**:
- 1. Enable the **Synchronize Group Memberships** toggle.
- 2. Click **New mapping**.
- 3. Enter the name of a group you added to Okta users, then click **Add**.
- 4. Select the Metabase groups to map the group name to.
- 5. Repeat steps 2 to 4 for each group.
- 6. In **Group attribute name**, enter `MetabaseGroupName` (the name of the SAML attribute statement).
- 7. Click **Save and enable**.
+ 1. Turn on the **Group mapping** toggle.
+ 2. Next to **Manual group mappings**, click **New**.
+ 3. Enter the name of a group you added to Okta users.
+ 4. Select the Metabase groups to map the group name to.
+ 5. Click **Add mapping**.
+ 6. Repeat steps 2 to 5 for each group.
+ 7. In **Group attribute name**, enter `MetabaseGroupName` (the name of the SAML attribute statement).
+ 8. Click **Save and enable**.
- ![Metabase group mapping](images/saml-okta-groups.png)
+ ![Metabase group mapping](images/saml-okta-groups.png)
### Map Okta User Groups to Metabase groups
@@ -183,24 +184,22 @@ You can create a custom user profile attribute and fill it with the Metabase gro
3. In **Metabase SAML settings**:
- 1. Enable the **Synchronize Group Memberships** toggle.
- 2. Click **New mapping**.
- 3. Enter the name of an Okta group, then click **Add**.
- 4. Select the Metabase groups to map the group name to.
- 5. Repeat steps 2 to 4 for each group.
- 6. In **Group attribute name**, enter `MetabaseGroupName` (the name of the SAML attribute statement).
- 7. Click **Save and enable**.
+ 1. Turn on the **Group mapping** toggle.
+ 2. Next to **Manual group mappings**, click **New**.
+ 3. Enter the name of an Okta group.
+ 4. Select the Metabase groups to map the group name to.
+ 5. Click **Add mapping**.
+ 6. Repeat steps 2 to 5 for each group.
+ 7. In **Group attribute name**, enter `MetabaseGroupName` (the name of the SAML attribute statement).
+ 8. Click **Save and enable**.
- ![Metabase group mapping](images/saml-okta-groups.png)
+ ![Metabase group mapping](images/saml-okta-groups.png)
## Troubleshooting SAML issues
For common issues, go to [Troubleshooting SAML][troubleshooting-saml].
-[enabling-saml-in-metabase]: ./authenticating-with-saml.md#enabling-saml-authentication-in-metabase
[okta-saml-docs]: https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm
-[okta-create-attribute-statement]: https://support.okta.com/help/s/article/How-to-define-and-configure-a-custom-SAML-attribute-statement
-[saml-doc]: ./authenticating-with-saml.md
[site-url]: ../configuring-metabase/settings.md#site-url
[troubleshooting-saml]: ../troubleshooting-guide/saml.md
diff --git a/docs/people-and-groups/start.md b/docs/people-and-groups/start.md
index b39e2b050ea..3e93e98914f 100644
--- a/docs/people-and-groups/start.md
+++ b/docs/people-and-groups/start.md
@@ -44,7 +44,7 @@ With [Pro and Enterprise plans](https://www.metabase.com/pricing), you have more
- [JWT][jwt]
- LDAP advanced features
- - [Group membership filter](./ldap.md#ldap-group-membership-filter)
+ - [Group membership filter](./ldap.md#group-membership-filter)
- [Syncing user attributes](./ldap.md#syncing-user-attributes-with-ldap)
- [OIDC][oidc]
- [Keycloak][oidc-keycloak]