The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs: auth settings UI (#82971)
Michael Eby3ec11a26abe1
diff --git a/docs/embedding/full-app-embedding-quick-start-guide.md b/docs/embedding/full-app-embedding-quick-start-guide.mdindex c97a6816c25..b4aa344409a 100644--- a/docs/embedding/full-app-embedding-quick-start-guide.md+++ b/docs/embedding/full-app-embedding-quick-start-guide.md@@ -47,17 +47,15 @@ If you're embedding Metabase in a different domain, you may need to [set the sesWhile still in the **Embedding settings** section, scroll down and click on **Authentication** under **Related settings**.-On the card that says **JWT**, click the **Setup** button (you may have to scroll down to view the JWT card).+On the card that says **JWT**, click the **Set up** button (you may have to scroll down to view the JWT card).-+#### Set JWT identity provider URI-#### Set JWT Identity provider URI--In your app, you'll create a route for SSO at `/sso/metabase`. In the **JWT IDENTITY PROVIDER URI** field, enter the URL of your SSO route. For example, our sample app runs on port 8080, so in that case this JWT IDENTITY PROVIDER URI could be `http://localhost:8080/sso/metabase`.+In your app, you'll create a route for SSO at `/sso/metabase`. In the **JWT Identity Provider URI** field, enter the URL of your SSO route. For example, our sample app runs on port 8080, so in that case this **JWT Identity Provider URI** could be `http://localhost:8080/sso/metabase`.#### Generate a JWT signing key-Click on the **Generate key** button to generate a signing key. Keep this key a secret. You'll use it on your server. If you generate another key, you'll overwrite the existing key, so you'll need to update the key in your app as well.+Click on the **Set up key** button to generate a signing key. Keep this key a secret. You'll use this JWT signing key on your server. If you generate another key, you'll overwrite the existing key, so you'll need to update the key in your app as well.Copy this key, as you'll need it in the next section.@@ -173,15 +171,20 @@ In Metabase, click the **grid** icon and go to **Admin** > **People** > **GroupsYou'll map this string in the `groups` key to a Metabase group, so that when the person signs in via SSO, Metabase automatically assigns them to the appropriate Metabase group.-In Metabase's admin section, go to **Authentication > JWT** and click **Edit**.+Go to **Admin** > **Settings** > **Authentication** > **JWT**.-In the **Group schema** section, toggle on **Synchronize group memberships**. If the names of groups in the `groups` array match Metabase group names exactly (e.g. both are `"Customer Acme"`), then the groups will be mapped automatically.+In the **Group mapping** section, select **Automatic**. Metabase adds people to the Metabase groups whose names match the group names in their JWT. If your `groups` array and your Metabase group both use `Customer Acme`, Metabase maps them for you.-If the JWT group names and Metabase group names don't match, then for each group you want to sync, add a group mapping. When you click **New mapping**, enter "Customer-Acme", the string that you included in the `groups` array in your JWT payload. You can then associate that group name with the Metabase group "Customer Acme" that we created earlier.+If your JWT group names and your Metabase group names don't match, select **Manual** instead:-+1. Click **New mapping**.+2. In the **JWT group name** field, enter `Customer-Acme`.+3. From **Metabase groups**, select **Customer Acme**.+4. Click **Add mapping**.-Be sure to **Save changes**.+Metabase saves each mapping as soon as you add it.++### CHECKPOINT: verify that Metabase assigns people to groups when they log indiff --git a/docs/embedding/images/jwt-setup.png b/docs/embedding/images/jwt-setup.pngdeleted file mode 100644index 193243e53f7..00000000000Binary files a/docs/embedding/images/jwt-setup.png and /dev/null differdiff --git a/docs/embedding/images/sync-groups.png b/docs/embedding/images/sync-groups.pngindex d4f02987812..4e67203da27 100644Binary files a/docs/embedding/images/sync-groups.png and b/docs/embedding/images/sync-groups.png differdiff --git a/docs/people-and-groups/authenticating-with-jwt.md b/docs/people-and-groups/authenticating-with-jwt.mdindex 62b7098aa19..2d71d8f8e97 100644--- a/docs/people-and-groups/authenticating-with-jwt.md+++ b/docs/people-and-groups/authenticating-with-jwt.md@@ -48,15 +48,15 @@ await fetch(`${METABASE_URL}/auth/sso?return_to=/question/1-superb-question`, {## Set up JWT authentication-Navigate to the **Admin**>**Settings** section of the Admin area, then click on the **Authentication > JWT** tab.--+Go to **Admin** > **Settings** > **Authentication** > **JWT**. Fill out the form, then click **Save and enable**.Here's a breakdown of each of the settings:- **JWT Identity Provider URI**: This is where Metabase will redirect login requests. It's where your users go to log in through your identity provider.-- **String Used by the JWT Signing Key**: The string used to seed the private key used to validate JWT messages. Both Metabase and the authentication app should have the same JWT signing key.+- **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.## User attribute configuration (optional)@@ -65,7 +65,7 @@ These are additional settings you can fill in to pass user attributes to Metabas- **Email attribute:** the key to retrieve each JWT user's email address.- **First name attribute:** the key to retrieve each JWT user's first name.- **Last name attribute:** if you guessed that this is the key to retrieve each JWT user's last name, well then you have been paying attention.-- **Group assignment attribute:** the key to retrieve each JWT user's group assignments.+- **Group assignment attribute:** the key to retrieve each JWT user's group assignments. [Group mapping](#configure-group-mappings) uses this key.- **Tenant attribute:** the key to retrieve each JWT user's tenant. Default is `@tenant`. See [Tenants](../embedding/tenants.md).You can send additional user attributes to Metabase by adding the attributes as key/value pairs to your JWT. These attributes will be synced on every login.@@ -78,14 +78,42 @@ You can configure JWT group assignments through Metabase's Admin interface, or b### Configure group mapping in Metabase-1. Add groups to your JWT: `groups: ["group_name"]`. The attribute key (e.g. `groups`) should match the **Group assignment attribute** in Metabase.-1. In Metabase JWT settings, under **Group Sync**, toggle on **Synchronize Group Memberships**-1. If the group names in your JWT match the Metabase group names, they will be synced automatically, and you don't need to set up mappings manually.+To add groups to your JWT, use the syntax `groups: ["group_name"]`, where `groups` is the attribute key. The key must match the **Group assignment attribute** in your JWT settings.++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.+- **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**.++To create manual mappings:++1. Select **Manual**.+2. Click **New mapping**.+3. In the **JWT group name** field, enter the name of a group from your JWT.+4. From **Metabase groups**, select the groups to add people in this JWT group to.+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 the mapping.-1. Otherwise, click **New mapping** and add the name of a JWT group.-1. In the row that appears, click the dropdown to pick the Metabase group(s) that this should map to.- -1. Repeat this for each of the groups you want to map.+++To edit or remove a mapping, hover over the mapping and click the pencil or trash 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:++- **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)++Removing members or deleting groups takes effect immediately and can't be undone!### Configure group mapping through environment variables@@ -109,17 +137,13 @@ You can use the following environment variables to configure JWT group mappingsYou can find Metabase Group ID in the URL for the group page, like `http://your-metabase-url/admin/people/groups/<ID>`. "All Users" group has ID 1 and "Administrators" group has ID 2.-### If group mappings are not specified, Metabase will match groups by name--If you don't specify any group mappings in Metabase's Admin settings or via `MB_JWT_GROUP_MAPPINGS` environment variables, then Metabase will try to assign Metabase groups to users based on the matching names. If the names of groups in the JWT group attribute array match Metabase group names exactly (e.g. both are `"Sales"`), then the groups will be mapped automatically.--If you add group mappings manually, Metabase will _not_ try to also match groups by names.+If you set either `MB_JWT_GROUP_SYNC` or `MB_JWT_GROUP_MAPPINGS`, the **Group mapping** section becomes read-only. `MB_JWT_GROUP_SYNC=true` with no mappings gives you automatic mapping. With mappings, Metabase uses only those mappings.## Creating Metabase accounts with SSO> 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. Metabase will create accounts for people who don't yet have a Metabase account but who are able to log in via JWT SSO.+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.If you disable user provisioning, users without accounts or with deactivated accounts will not be able to log in via JWT SSO.@@ -129,7 +153,7 @@ Metabase accounts created with an external identity provider login don't have pa> **Avoid locking yourself out of your Metabase!** This setting will apply to all Metabase accounts, _including your Metabase admin account_. We recommend that you keep password authentication **enabled**. This will safeguard you from getting locked out of Metabase in case of any problems with SSO.-To require people to log in with SSO, disable password authentication from **Admin** > **Settings** > **Authentication**.+To require people to log in with SSO, go to **Admin** > **Settings** > **Authentication** > **Overview** and disable the **Enable password authentication** toggle.diff --git a/docs/people-and-groups/authenticating-with-saml.md b/docs/people-and-groups/authenticating-with-saml.mdindex 9b5dbd868e6..1db28e6851c 100644--- a/docs/people-and-groups/authenticating-with-saml.md+++ b/docs/people-and-groups/authenticating-with-saml.md@@ -20,15 +20,15 @@ Before setting up SAML, make sure you know the password for your Metabase admin## Setting up SAML with your IdP in Metabase-Once you've [confirmed the password to your Metabase admin account](#confirm-the-password-for-your-metabase-admin-account), head over to the **Settings** section of the Admin Panel, then click on the **Authentication** tab. Click the **Set up** button in the SAML section of the Authentication page, and you'll see this form:+After you [confirm the password for your Metabase admin account](#confirm-the-password-for-your-metabase-admin-account), go to **Admin** > **Settings** > **Authentication**. In the **SAML** section, click **Set up**. You can also click **SAML** in the sidebar under **Authentication**.-+The form includes the following sections:-The form includes three sections:--1. [Metabase info that you'll have to input into your identity provider (IdP)](#generic-saml-configuration).-2. [IdP info that you'll need to tell Metabase about](#enabling-saml-authentication-in-metabase).-3. [Signing SSO requests (optional)](#settings-for-signing-sso-requests-optional).+1. [Configure your identity provider (IdP)](#generic-saml-configuration)+2. [Tell Metabase about your identity provider](#enabling-saml-authentication-in-metabase)+3. [User provisioning](#user-provisioning)+4. [Signing SSO requests (optional)](#settings-for-signing-sso-requests-optional)+5. [Group mapping](#group-mapping)## SAML guides@@ -54,7 +54,7 @@ User provisioning is enabled by default. Metabase will create accounts for peoplIf you disable user provisioning, users without accounts or with deactivated accounts will not be able to log in.-If you've set up [User provisioning with SCIM](./user-provisioning.md), you'll want to turn this setting off so that Metabase doesn't automatically create a new account for anyone who authenticates successfully, as you may want to use SCIM to determine who can and can't create an account in Metabase.+If you manage user provisioning with [SCIM](./user-provisioning.md), you can't turn on SAML user provisioning.## Generic SAML configuration@@ -82,7 +82,7 @@ Different IdPs use different names for the redirect URL. Here are some common ex| [Okta](saml-okta.md) | Single Sign On URL || OneLogin | ACS (Consumer) URL |-### User attributes+### SAML attributesMetabase will automatically log in people who've been authenticated by your SAML identity provider. To do so, the first assertion returned in the identity provider's SAML response _must_ contain attributes for each person's first name, last name, and email.@@ -92,10 +92,6 @@ Generally you'll need to paste these user attributes (first name, last name, and> 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.-### Settings for signing SSO requests (optional)--These are additional settings you can fill in to sign SSO requests to ensure they don’t get tampered with.-## Enabling SAML authentication in MetabaseMetabase will now need to know some things about your IdP. Here's a breakdown of each of the settings:@@ -112,18 +108,6 @@ Different IdPs use different names for the Identity Provider URL. Here are some| [Okta](saml-okta.md) | Identity Provider Single-Sign On URL || OneLogin | SAML 2.0 Endpoint (HTTP) |-### SAML identity provider issuer--The SAML identity provider issuer is a unique identifier for the IdP. You might also see "Issuer" referred to as "Entity ID". Assertions from the IdP will contain this information, and Metabase will verify that the issuer matches the value you set.--We recommend that you set this value to make your SAML configuration more secure.--| Provider | Name |-| ---------------------- | --------------------------- |-| [Auth0](saml-auth0.md) | Identity Provider Login URL |-| [Okta](saml-okta.md) | Identity Provider Issuer |-| OneLogin | Issuer URL |-### SAML identity provider certificateThe SAML identity provider certificate is an encoded certificate that Metabase will use when connecting to the IdP URI. The certificate will look like a big blob of text that you'll want to copy and paste carefully — the spacing is important!@@ -138,6 +122,20 @@ Note that your certificate text may include header and footer comments that look| [Okta](saml-okta.md) | X.509 Certificate || OneLogin | X.509 Certificate |+### SAML application name++Metabase uses the application name in requests to your IdP. The default is `Metabase`.++### SAML identity provider issuer++The SAML identity provider issuer is a required unique identifier for the IdP. You might also see the issuer called "Entity ID." Assertions from the IdP include the issuer, and Metabase verifies that it matches the value you enter.++| Provider | Name |+| ---------------------- | --------------------------- |+| [Auth0](saml-auth0.md) | Identity Provider Login URL |+| [Okta](saml-okta.md) | Identity Provider Issuer |+| OneLogin | Issuer URL |+### Settings for signing SSO requests (optional)To sign requests so that they can't be tampered with, you'll need to provide additional settings.@@ -172,26 +170,38 @@ SLO isn’t configurable from the Metabase interface. To enable it, you’ll neeFor the `MB_SESSION_COOKIE_SAMESITE` setting to work with `none`, Metabase must be served over HTTPS. Browsers like Chrome will block cookies in cross-site requests if SSL is not enabled. Without HTTPS, logout requests from your IdP (such as Okta) won’t include the session cookie, which means Metabase won’t be able to end the session properly.-## Synchronizing group membership with your IdP+## Group mapping-This setting allows you to assign users to Metabase groups based on an attribute of your users in your IdP. This setting may not correlate to group functionality provided by your IdP; you may need to create a separate user attribute to set people's Metabase groups, like `metabaseGroups`.+Group mapping lets you assign people to Metabase groups based on an attribute of your users in your IdP. This setting may not correlate to group functionality provided by your IdP; you may need to create a separate user attribute to set people's Metabase groups, like `metabaseGroups`.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-Once you've gotten everything set up in your SAML provider, you'll need to configure the group schema in Metabase.+After you set up the group attribute in your IdP, configure group mappings:-1. Turn on the **Synchronize group memberships** setting.-2. Click **Edit mappings**.-3. Click **Create a mapping**.-4. Enter in the name of one of the groups you entered as your `metabaseGroups` attribute values, then click the **Add** button.-5. Click the dropdown that appears under the `Groups` heading to select the Metabase group(s) that users with this particular `metabaseGroups` value should be added to.-6. Click **Save**.-7. After that, type in the name of the user attribute you added in your SAML provider. In this case, we told Okta that the `metabaseGroups` attribute should be named `MetabaseGroupName`, so that's what we'll enter in the Group Attribute Name field in Metabase.+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**.+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**.++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**.+### Remove a group mapping++To remove a mapping, click the **X** next to it. Choose what to do with the groups in the mapping:++- **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)++Removing members or deleting groups takes effect immediately and can't be undone.+## Creating Metabase accounts with SSO> Paid plans [charge for each additional account](https://www.metabase.com/how-billing-works#what-counts-as-a-user-account).@@ -204,13 +214,13 @@ Metabase accounts created with an external identity provider login don't have pa> **Avoid locking yourself out of your Metabase!** Turning off password logins applies to all Metabase accounts, _including your Metabase admin account_. Before turning off password logins, make sure you can log in to your admin account using SSO.-To _require_ people to log in with SSO, disable password authentication from **Admin settings** > **Authentication**. Turn off the **Enable Password Authentication** toggle.+To require people to log in with SSO, go to **Admin** > **Settings** > **Authentication** > **Overview** and disable the **Enable password authentication** toggle.## New account notification emails-When people log in to Metabase for the first time via SSO, Metabase will automatically create an account for them, which will trigger an email notification to Metabase administrators. If you don't want these notifications to be sent, go to **Admin settings > Authentication > User provisioning**, and toggle off **"Notify admins of new users provisioned from SSO"**+When people log in to Metabase for the first time via SSO, Metabase will automatically create an account for them, which will trigger an email notification to Metabase administrators. If you don't want these notifications to be sent, go to **Admin** > **Settings** > **Authentication** > **User provisioning**, and toggle off **"Notify admins of new users provisioned from SSO"**## Example code using SAMLdiff --git a/docs/people-and-groups/images/JWT-auth-form.png b/docs/people-and-groups/images/JWT-auth-form.pngdeleted file mode 100644index 4f2afed5b6f..00000000000Binary files a/docs/people-and-groups/images/JWT-auth-form.png and /dev/null differdiff --git a/docs/people-and-groups/images/jwt-groups.png b/docs/people-and-groups/images/jwt-groups.pngindex b90d264d2d3..7e54b6c2029 100644Binary files a/docs/people-and-groups/images/jwt-groups.png and b/docs/people-and-groups/images/jwt-groups.png differdiff --git a/docs/people-and-groups/images/ldap-attributes.png b/docs/people-and-groups/images/ldap-attributes.pngindex bb8d2fb2f23..bd2d9ea4f81 100644Binary files a/docs/people-and-groups/images/ldap-attributes.png and b/docs/people-and-groups/images/ldap-attributes.png differdiff --git a/docs/people-and-groups/images/ldap-group-mapping.png b/docs/people-and-groups/images/ldap-group-mapping.pngindex ce5b0e74153..228c06c03c6 100644Binary files a/docs/people-and-groups/images/ldap-group-mapping.png and b/docs/people-and-groups/images/ldap-group-mapping.png differdiff --git a/docs/people-and-groups/images/password-disable.png b/docs/people-and-groups/images/password-disable.pngindex 2fad57899ae..7749de205da 100644Binary files a/docs/people-and-groups/images/password-disable.png and b/docs/people-and-groups/images/password-disable.png differdiff --git a/docs/people-and-groups/images/saml-form.png b/docs/people-and-groups/images/saml-form.pngdeleted file mode 100644index fc1a68c6336..00000000000Binary files a/docs/people-and-groups/images/saml-form.png and /dev/null differdiff --git a/docs/people-and-groups/images/saml-okta-groups.png b/docs/people-and-groups/images/saml-okta-groups.pngindex 9df2d9fb1df..4ddac56b4af 100644Binary files a/docs/people-and-groups/images/saml-okta-groups.png and b/docs/people-and-groups/images/saml-okta-groups.png differdiff --git a/docs/people-and-groups/ldap.md b/docs/people-and-groups/ldap.mdindex 4295ea64c4e..d3fcb9ea33d 100644--- a/docs/people-and-groups/ldap.md+++ b/docs/people-and-groups/ldap.md@@ -6,17 +6,15 @@ title: LDAPMetabase supports authentication with Lightweight Directory Access Protocol (LDAP).-You can find SSO options under **Admin** > **Settings** > **Authentication**.-## Required LDAP attributesYou need to set up your LDAP directory with these attributes:- email (defaulting to the `mail` attribute)-- first name (defaulting to the `givenName` attribute)+- first name (defaulting to the `givenname` attribute)- last name (defaulting to the `sn` attribute).-If your LDAP setup uses other attributes for these, you can edit this under the "Attributes" portion of the form.+If your LDAP setup uses other attributes for these, you can change them in the **Attributes** section of the LDAP settings page. The section becomes available after you save your server settings.@@ -24,31 +22,31 @@ Your LDAP directory must have the email field populated for each entry that will## Enabling LDAP authentication-In the **Admin** > **Settings** > **Authentication** > **LDAP**. Click the toggle at the top of the form to enable LDAP, then fill out the form with the relevant details.+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. Metabase will create accounts for people who don't yet have a Metabase account but who are able to log in via LDAP.+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.## Server settings-- LDAP Host. Your server name. E.g., ldap.yourdomain.org-- LDAP Port. The Server port, usually 389 or 636 if SSL is used.-- LDAP Security settings. Options are None, SSL, or StarTLS.-- LDAP admin username. The distinguished name to bind as (if any). This user will be used to look up information about other users.-- LDAP admin password.+- **LDAP host** (required): Your server hostname. For example, `ldap.yourdomain.org`.+- **LDAP port**: The server port, usually 389, or 636 if you use SSL.+- **LDAP security**: None, SSL, or StartTLS.+- **Username or DN**: The distinguished name to bind as, if any. Metabase uses this name to look up information about other users.+- **Password**: The password to bind with for the lookup user.Then save your changes. Metabase will automatically pull the [required attributes](#required-ldap-attributes) from your LDAP directory.## 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.+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.### User search base-The **User search base** field should be completed with the _distinguished name_ (DN) of the entry in your LDAP server that is the starting point when searching for users.+**User search base** is required. Enter the _distinguished name_ (DN) of the entry in your LDAP server that Metabase should use as the starting point when searching for users.For example, let's say you're configuring LDAP for your company, WidgetCo, where your base DN is `dc=widgetco,dc=com`. If entries for employees are all stored within an organizational unit in your LDAP server named `People`, you'll want to supply the user search base field with the DN `ou=People,dc=widgetco,dc=com`. This tells Metabase to begin searching for matching entries at that location within the LDAP server.@@ -64,31 +62,38 @@ When a person logs into Metabase, this command confirms that the login they suppThis default command will work for most LDAP servers, since `inetOrgPerson` is a widely-adopted objectClass. But if your company for example uses a different objectClass to categorize employees, this field is where you can set a different command for how Metabase finds and authenticates an LDAP entry upon a person logging in.-## LDAP group mapping+## Group mapping++Instead of manually assigning people to [groups](./managing.md#groups), use [group mappings](https://www.metabase.com/learn/metabase-basics/administration/permissions/ldap-auth-access-control#group-management) to assign them based on their LDAP groups.-Manually assigning people to [groups](./managing.md#groups) in Metabase after they've logged in via SSO can get tedious. Instead, you can take advantage of the groups that already exist in your LDAP directory by enabling [group mappings](https://www.metabase.com/learn/metabase-basics/administration/permissions/ldap-auth-access-control#group-management).+To map an LDAP group to a Metabase group:-Scroll to **Group Schema** on the same LDAP settings page, and click the toggle to enable group mapping. Selecting **Edit Mapping** will bring up a modal where you can create and edit mappings, specifying which LDAP group corresponds to which Metabase group.+1. In the **Group mapping** section, turn on the toggle.+2. Next to **Manual group mappings**, click **New**.+3. Enter the distinguished name for the LDAP group, such as `cn=Accounting,ou=Groups,dc=example,dc=org`.+4. From **Pick Metabase group**, select the Metabase groups that people in this LDAP group should be added to.+5. Click **Add mapping**.+6. Repeat steps 2 to 5 for each group you want to map.-As you can see below, if you have an **Accounting** group in both your LDAP server and Metabase instance, you'll just need to supply the Distinguished Name from your LDAP server (in the example, it's `cn=Accounting,ou=Groups,dc=widgetco,dc=com`) and select its match from the dropdown of your existing Metabase groups.+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.Some things to keep in mind regarding group mapping:-- The Administrator group works like any other group.+- The Administrators group works 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 groups in your Metabase that don't have an LDAP mapping.+- 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-{% include plans-blockquote.html feature="LDAP advanced features" %}+{% 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.## Syncing user attributes with LDAP-{% include plans-blockquote.html feature="LDAP advanced features" %}+{% include plans-blockquote.html feature="LDAP advanced features" is_plural=true %}You can manage [user attributes][user-attributes-def] such as names, emails, and roles from your LDAP directory. When you set up [row and column security][row-and-column-security], your LDAP directory will be able to [pass these attributes][user-attributes-docs] to Metabase.diff --git a/docs/people-and-groups/saml-keycloak.md b/docs/people-and-groups/saml-keycloak.mdindex 32ad5428175..d1dbbdcb858 100644--- a/docs/people-and-groups/saml-keycloak.md+++ b/docs/people-and-groups/saml-keycloak.md@@ -48,11 +48,11 @@ For more information, check out our guide for [authenticating with SAML](./authe1. Go to your Metabase **Admin** > **Settings** > **Authentication** > **SAML**.2. From the XML file from Step 7 above:- - **SAML Identity Provider URL**: Insert the URL that appears right after the following string: `Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location=`- - **SAML Identity Provider Issuer**: Insert the URL that appears right after `entityID=`.- - **SAML Identity Provider Certificate**: Input the long string that appears after the `<X509Certificate>` tag. Take care when inserting this string: if any letters or special characters are added or off, the setup won't work.- - **SAML Application Name**: `metabase`-3. Click **Save Changes**.+ - **SAML identity provider URL**: Insert the URL that appears right after the following string: `Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location=`+ - **SAML identity provider certificate**: Input the long string that appears after the `<X509Certificate>` tag. Take care when inserting this string: if any letters or special characters are added or off, the setup won't work.+ - **SAML identity provider issuer**: Insert the URL that appears right after `entityID=`.+ - **SAML application name**: `metabase`+3. Click **Save and enable**.## Mapping attributes from users in Keycloak to Metabase@@ -86,13 +86,17 @@ In your Keycloak client:### Set up group mapping in Metabase-1. In Admin, go to **Authentication > SAML**.-2. In SAML settings, toggle on **Synchronize Group Memberships**-3. For each of the Keycloak groups, set up a new mapping to a Metabase group.+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**.- Currently, Keycloak groups will show up in Metabase with the slash character ("/") prepended to the group name. So, for example, a group named `sales` in Keycloak shows up in Metabase as `/sales`.+ 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`.-4. In **Group attribute name**, enter `member_of` (the name for the attribute with the group list in your Keycloak configuration).+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**.## Troubleshooting SAML issuesdiff --git a/docs/people-and-groups/saml-okta.md b/docs/people-and-groups/saml-okta.mdindex faeafa968db..57096ce8e3f 100644--- a/docs/people-and-groups/saml-okta.md+++ b/docs/people-and-groups/saml-okta.md@@ -16,11 +16,7 @@ See [authenticating with SAML](./authenticating-with-saml.md) for general SAML i## Turn on SAML-based SSO in Metabase-In the **Admin**>**Settings** section of the Admin area, go to the **Authentication** tab and click on **Set up** under **SAML**.--You'll see a SAML configuration form like this:--+Go to **Admin** > **Settings** > **Authentication**. In the **SAML** section, click **Set up**.You'll need to use the information in this form to set up SAML in Okta.@@ -34,7 +30,7 @@ From the Okta **Admin** console, [create a new SAML app integration][okta-saml-d### Configure Okta SAML settings-To configure Okta app integration with Metabase, you'll need to use the information found in Metabase in the **Admin panel** > **Authentication** > **SAML** section.+To configure Okta app integration with Metabase, you'll need to use the information found in Metabase in the **Admin** > **Settings** > **Authentication** > **SAML** section.#### General settings@@ -59,7 +55,7 @@ Even though Okta says these are optional, Metabase requires them. Okta will pass| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` | user.firstName || `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | user.lastName |-The names of attribute statements in Okta should match the attribute names in Metabase (names are case sensitive). If you want to use non-default attribute names in your Okta app configuration, you will also need to change the names for the attribute fields in Metabase in **Admin panel** > **Authentication** > **SAML**.+The names of attribute statements in Okta should match the attribute names in Metabase (names are case sensitive). If you want to use non-default attribute names in your Okta app configuration, you will also need to change the names for the attribute fields in Metabase in **Admin** > **Settings** > **Authentication** > **SAML**.> **Make sure that people [cannot edit their email address attribute](https://help.okta.com/oie/en-us/content/topics/users-groups-profiles/usgp-user-edit-attributes.htm)**. To log people in to your Metabase (or to create a Metabase account on first login), your IdP will pass the email address attribute to Metabase. If a person can change the email address attribute, they'll potentially be able to access Metabase accounts other than their own.@@ -115,7 +111,7 @@ Once you set up your SAML app in Okta, you'll need to configure SAML in Metabase2. Go to the **Sign On** tab.3. Click on **View SAML setup instructions**.-Use the information from Okta SAML instructions to fill the Metabase SAML form in **Admin panel** > **Authentication** > **SAML**:+Use the information from Okta SAML instructions to fill the Metabase SAML form in **Admin** > **Settings** > **Authentication** > **SAML**:| Metabase SAML | Okta SAML || ---------------------------------- | ------------------------------------ |@@ -156,11 +152,15 @@ You can create a custom user profile attribute and fill it with the Metabase gro4. In **Metabase SAML settings**:-- Turn on **Synchronize Group Memberships**.-- For each of the groups you added to Okta users, set up a new mapping to a Metabase group.-- In **Group attribute name**, enter `MetabaseGroupName` (the name of the SAML attribute statement).+ 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**.- + ### Map Okta User Groups to Metabase groups@@ -183,11 +183,15 @@ You can create a custom user profile attribute and fill it with the Metabase gro3. In **Metabase SAML settings**:-- Turn on **Synchronize Group Memberships**.-- For each of the groups you added to Okta users, set up a new mapping to a Metabase group.-- In **Group attribute name**, enter `MetabaseGroupName` (the name of the SAML attribute statement).+ 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**.- + ## Troubleshooting SAML issues