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 - OIDC (#70892)
Jeff Bruemmerc3c7feeddf49
diff --git a/docs/README.md b/docs/README.mdindex 5e6dea3e994..c8a93a6fe23 100644--- a/docs/README.md+++ b/docs/README.md@@ -180,6 +180,8 @@ Metabase's reference documentation.#### Paid SSO options- [JWT-based authentication](./people-and-groups/authenticating-with-jwt.md)+- [OIDC-based authentication](./people-and-groups/authenticating-with-oidc.md)+ - [OIDC with Keycloak](./people-and-groups/oidc-keycloak.md)- [SAML-based authentication](./people-and-groups/authenticating-with-saml.md)- [SAML with Auth0](./people-and-groups/saml-auth0.md)- [SAML with Microsoft Entra ID](./people-and-groups/saml-azure.md)diff --git a/docs/people-and-groups/authenticating-with-oidc.md b/docs/people-and-groups/authenticating-with-oidc.mdnew file mode 100644index 00000000000..e3fbc3411e9--- /dev/null+++ b/docs/people-and-groups/authenticating-with-oidc.md@@ -0,0 +1,169 @@+---+title: OIDC-based authentication+summary: Set up OIDC single sign-on in Metabase.+---++# OIDC-based authentication++{% include plans-blockquote.html feature="OIDC authentication" %}++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.++## Self-hosted Metabases must set an encryption key++> Metabase Cloud encrypts credentials by default, so this section only applies to self-hosted Metabases.++[`MB_ENCRYPTION_SECRET_KEY`](../configuring-metabase/environment-variables.md#mb_encryption_secret_key) must be set before enabling OIDC. Metabase uses this key to encrypt the OIDC state cookie. Without it, Metabase will return a 500 error when a person tries to log in via OIDC.++Set this key in your environment before starting Metabase:++```+MB_ENCRYPTION_SECRET_KEY=your-secret-key-at-least-16-characters+```++Once you set an encryption key, don't remove it. Metabase encrypts values in the database with this key and will refuse to start without it.++For more, see [Encrypting your database connection](../databases/encrypting-details-at-rest.md).++## Set up OIDC in Metabase++_Admin > Settings > Authentication > OIDC_++You can also configure OIDC with [environment variables](#environment-variables).++You'll need to enter the following:++| Field | Description |+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| **Key** | A unique identifier for this provider. Lowercase letters, numbers, and hyphens only. Can't be changed after creation. Use a name that describes the provider (e.g., `keycloak`), not the application. Metabase constructs the redirect URI as `{site-url}/auth/sso/{key}/callback`. Configure this exact URI in your IdP, so choose the key _before_ configuring your IdP for Metabase. The full redirect URI is shown in the admin UI after you enter the key. |+| **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"]`).++### Attribute mapping++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` |++If your IdP uses different claim names, update these fields to match.++## Synchronize group membership++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++> 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).++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**.++### How group sync 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.+- If the groups claim is missing from the token entirely, Metabase leaves existing group memberships unchanged.++## 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.++If the check reports "OIDC discovery succeeded, but credentials could not be verified", this could mean you need to configure the client to support the grant type Metabase uses for testing. In a Keycloak client, for example, you should turn on **Service accounts roles** and **Client authentication**.++## User provisioning++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.++### How auto-provisioning works++If auto-provisioning is on, when someone logs in via OIDC, Metabase will look up the account by email (case-insensitive). If an account with that email already exists, Metabase links the OIDC identity to that existing account. On each OIDC login, Metabase updates the account's name from the IdP's claims. Otherwise, Metabase will automatically create a new account.++If auto-provisioning is off, and no matching account exists, the person gets an error, and can't log in.++## Environment variables++You can also configure OIDC via environment variables instead of the admin UI. Settings configured via environment variables are read-only in the admin UI.++- [`MB_OIDC_ALLOWED_NETWORKS`](../configuring-metabase/environment-variables.md#mb_oidc_allowed_networks): controls which networks OIDC requests are allowed to reach. Possible values: `allow-all` (default, no restrictions), `allow-private` (allows external and private networks, but blocks localhost and loopback), or `external-only` (blocks requests to private networks).+- [`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.++See [Environment variables](../configuring-metabase/environment-variables.md).++## Disable password logins++> **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**.++## OIDC example provider guide++For a step-by-step walkthrough, see [Keycloak](./oidc-keycloak.md).diff --git a/docs/people-and-groups/oidc-keycloak.md b/docs/people-and-groups/oidc-keycloak.mdnew file mode 100644index 00000000000..214f8d06840--- /dev/null+++ b/docs/people-and-groups/oidc-keycloak.md@@ -0,0 +1,111 @@+---+title: OIDC with Keycloak+summary: Step-by-step guide to setting up Keycloak as an OIDC identity provider for Metabase.+---++# OIDC with Keycloak++{% include plans-blockquote.html feature="OIDC authentication" %}++Keycloak is an open-source identity provider that supports [OpenID Connect (OIDC) authentication](./authenticating-with-oidc.md) out of the box.++1. [Set up OIDC in Keycloak](#set-up-oidc-in-keycloak) (the identity provider).+2. [Set up OIDC in Metabase](./authenticating-with-oidc.md#set-up-oidc-in-metabase) (the service provider).+3. [Sync groups from Keycloak to Metabase](#sync-groups-from-keycloak-to-metabase) (optional).++## Set up OIDC in Keycloak++Set up a realm, user, and client in Keycloak for Metabase.++1. In Keycloak, sign in as an administrator and go to the admin console.++2. Create a new [realm](https://www.keycloak.org/docs/latest/server_admin/index.html#core-concepts-and-terms) for Metabase.++3. Create a user in that realm from **Users** > **Add user**.++ 1. Fill in **Email**, **First name**, and **Last name**. The email field is required because Metabase uses this email as the account identifier. Metabase maps these fields to user properties.+ 2. Turn on **Email verified**. Without verification, Keycloak won't allow the person to log in.+ 3. Make sure **Required user actions** is empty. If any actions are listed, remove them. Keycloak blocks login until required actions are completed.+ 4. Click **Create**, then go to the user's **Credentials** (on the top menu, not the side menu).+ 5. Click **Set password**, enter a password, and turn off the **Temporary** toggle.++4. Create a new client from **Clients** > **Create client**.++ 1. Set **Client type** to `OpenID Connect`.+ 2. Enter a **Client ID** (e.g., `metabase-client`).+ 3. Click **Next**.++5. On the **Capability config** page:++ 1. Turn on **Client authentication** (this makes the client confidential and enables the client secret).+ 2. Turn on **Service accounts roles**. Metabase's **Check connection** test authenticates using the OAuth 2.0 client credentials grant, which requires service accounts. If service accounts aren't allowed, the test returns "the identity provider does not support the grant type used for testing".+ 3. Click **Next**.++ > If you keep getting the "grant type" error even with **Service accounts roles** on, double-check the client secret in Metabase. You can check the Keycloak event log (**Events** in the Keycloak sidebar) for a `CLIENT_LOGIN_ERROR` entry to confirm (you'll need to have turned on [event logging](https://www.keycloak.org/docs/latest/server_admin/index.html#configuring-auditing-to-track-events)).++6. On the **Login settings** page:++ 1. Set **Valid redirect URIs** to `{metabase-url}/auth/sso/{key}/callback`, where `{key}` is the key you'll use when configuring OIDC in Metabase (like `keycloak`).+ 2. Set **Web origins** to your Metabase URL (like `https://metabase.your-company.com`).+ 3. Click **Save**.++7. Go to the client's **Credentials** tab and copy the client secret.++## Set up OIDC in Metabase++If you're self-hosting Metabase, make sure you've set `MB_ENCRYPTION_SECRET_KEY` before enabling OIDC. See [OIDC-based authentication](./authenticating-with-oidc.md#self-hosted-metabases-must-set-an-encryption-key) for details.++Go to **Admin settings** > **Authentication** > **OIDC** and enter:++| Field | Value |+| ----------------- | ------------------------------------------------------- |+| **Key** | e.g., `keycloak` |+| **Login prompt** | e.g., `Sign in with Keycloak` |+| **Issuer URI** | `{keycloak-url}/realms/{realm-name}` |+| **Client ID** | The Client ID from step 4 |+| **Client Secret** | The client secret from the client's **Credentials** tab |++See [OIDC-based authentication](./authenticating-with-oidc.md#set-up-oidc-in-metabase) for more on the Issuer URI (including container/Docker networking considerations).++Click **Check connection**, then **Save and enable**.++If the connection check fails with "the identity provider does not support the grant type used for testing", check:++- **Service accounts are enabled**: Make sure **Service accounts roles** is on in Keycloak's **Capability config** settings for this client. (Requires **Client authentication** to be on first.)+- **You have the correct client secret**: In Keycloak, go to **Clients** > your client > **Credentials** tab, click **Regenerate**. Then re-enter the new secret in Metabase.++Check the [Keycloak event log](https://www.keycloak.org/docs/latest/server_admin/index.html#auditing-user-events) (**Events** in the Keycloak sidebar) for a `CLIENT_LOGIN_ERROR` entry to narrow down the issue. (You may need to enable event logging first under **Realm settings** > **Events** > **Event listeners**.)++- `unauthorized_client` means service accounts aren't enabled.+- `invalid_client` means the secret is wrong.++## 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).++## Sync groups from Keycloak to Metabase++You can configure Keycloak to include a groups claim in the OIDC token, then set up Metabase to sync group memberships based on that claim.++### Add a groups claim in Keycloak++1. In the Keycloak admin console, go to **Clients** and select your Metabase client (e.g., `metabase-client`).+2. Go to the **Client scopes** tab and click the dedicated scope (e.g., `metabase-client-dedicated`).+3. Click **Add mapper** > **By configuration**.+4. Select **Group Membership** from the list.+5. Configure the mapper:+ - **Name**: `groups` (or any descriptive name).+ - **Token Claim Name**: `groups`. This is the claim name Metabase will look for. It must match the **Group attribute name** you set in Metabase.+ - **Full group path**: When on, group names include the full path (e.g., `/engineering`). The group name in your Metabase mapping must exactly match the value in the token.+ - **Add to ID token**: On.+6. Click **Save**.++### Configure group sync 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.++## Verify the setup++1. Open an incognito window and go to your Metabase URL. The sign-in screen should show a button with your login prompt text.+2. Click the button. You should be redirected to Keycloak's login page.+3. Log in with the user you created. Metabase should create the account and log you in. If you've configured group sync, check that they've been added to the correct group.diff --git a/docs/people-and-groups/start.md b/docs/people-and-groups/start.mdindex bc0a3d3051f..fbce7335017 100644--- a/docs/people-and-groups/start.md+++ b/docs/people-and-groups/start.md@@ -44,6 +44,8 @@ With [Pro and Enterprise plans](https://www.metabase.com/pricing/), you have mor- LDAP advanced features- [Group membership filter](./ldap.md#ldap-group-membership-filter)- [Syncing user attributes](./ldap.md#syncing-user-attributes-with-ldap)+- [OIDC][oidc]+ - [Keycloak][oidc-keycloak]- [SAML][saml]- [Auth0][saml-auth0]- [Microsoft Entra ID][azure-ad]@@ -59,6 +61,8 @@ Create keys to authenticate API calls.Metabase supports user provisioning via the SCIM protocol.+[oidc]: ./authenticating-with-oidc.md+[oidc-keycloak]: ./oidc-keycloak.md[azure-ad]: ./saml-azure.md[google-sign-in]: ./google-and-ldap.md#enabling-google-sign-in[jwt]: ./authenticating-with-jwt.mddiff --git a/docs/people-and-groups/user-provisioning.md b/docs/people-and-groups/user-provisioning.mdindex 0f33e31be5c..af0227cc9ff 100644--- a/docs/people-and-groups/user-provisioning.md+++ b/docs/people-and-groups/user-provisioning.md@@ -48,9 +48,7 @@ Copy the token and save the token somewhere safe. For security, Metabase can't sOnce you've enabled SCIM in Metabase and gotten your SCIM endpoint URL and SCIM token, follow the docs for [Setting up SCIM in Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_scim.htm?cshid=ext_Apps_App_Integration_Wizard-scim).-With Okta, Metabase supports user and group provisioning; groups are created and populated in Metabase.--NOTE: the authentication mode you need to set is "HTTP Header"+With Okta, Metabase supports user and group provisioning; groups are created and populated in Metabase. The authentication mode you need to set is "HTTP Header".## SCIM with Microsoft Entra ID@@ -63,3 +61,4 @@ With Microsoft Entra ID, Metabase only supports user provisioning (groups aren't- [Authenticating with SAML](./authenticating-with-saml.md)- [SAML with Okta](./saml-okta.md)- [SAML with Microsoft Entra ID](./saml-azure.md)+- [OIDC-based authentication](./authenticating-with-oidc.md)