基于 SAML 的身份验证

将您的 SSO 与 Metabase 集成，可以允许您

• 在用户首次登录 Metabase 时自动为其创建 Metabase 账户。
• 自动将用户属性从您的 SSO 传递到 Metabase，以支持 行和列安全。
• 让用户在无需重新认证的情况下访问 Metabase。

确认您的 Metabase 管理员账户的密码

在设置 SAML 之前，请确保您知道 Metabase 管理员账户的密码。如果在设置过程中遇到任何问题，可以通过登录屏幕上的“管理员备用登录”选项进行登录。

在 Metabase 中设置 SAML 与您的 IdP

在 确认您的 Metabase 管理员账户密码 后，前往管理员面板的“设置”部分，然后点击“认证”选项卡。点击认证页面 SAML 部分的“设置”按钮，您将看到此表单

该表单包含三个部分

1. 您需要在身份提供商 (IdP) 中输入的 Metabase 信息.
2. 您需要告知 Metabase 的 IdP 信息.
3. 对 SSO 请求进行签名（可选）.

SAML 指南

首先，您需要确保与您的 IdP 配置正确。每个 IdP 处理 SAML 设置的方式不同。

我们为最常见的提供商撰写了一些指南

• Auth0
• Microsoft Entra ID
• Google
• Keycloak
• Okta

如果您在此处未看到您的 IdP

• 请参阅您的 IdP 关于配置 SAML 的参考文档。您需要查找类似这样的内容 OneLogin SAML 指南。
• 使用 Metabase SAML 表单中的信息，填写您的 IdP 的 SAML 表单。
• 有关更多信息，请参阅下一节 通用 SAML 配置。

用户配置

默认情况下，Metabase 会为尚未拥有 Metabase 账户但可以通过 SAML SSO 登录的用户创建账户。

如果您设置了 使用 SCIM 进行用户配置，您将希望关闭此设置，以免 Metabase 为成功通过身份验证的任何人自动创建新账户，因为您可能希望使用 SCIM 来确定谁可以创建 Metabase 账户，谁不能。

通用 SAML 配置

Metabase 中的 SAML 表单的顶部部分包含您需要填入 IdP SAML 表单的信息，并附带方便复制信息的按钮。

Metabase SAML 表单中的字段名称不一定与您的 IdP 使用的名称匹配。我们提供了每个字段的说明，以帮助您将信息从一个地方映射到另一个地方。

IdP 应重定向回的 URL

重定向 URL 是用户在通过您的 IdP 登录后将被发送到的网络地址。要将用户重定向到您的 Metabase，您的重定向 URL 应该是您的 Metabase 站点 URL，并在末尾加上 /auth/sso。

例如，如果您的 Metabase 站点 URL 是 https://metabase.yourcompany.com，您将在 IdP 的 SAML 表单中使用

https://metabase.yourcompany.com/auth/sso

作为重定向 URL。

不同的 IdP 对重定向 URL 使用不同的名称。以下是一些常见示例

用户属性

Metabase 将自动登录已被您的 SAML 身份提供商认证的用户。为此，身份提供商的 SAML 响应中返回的第一个断言 *必须* 包含每个用户的名字、姓氏和电子邮件属性。

大多数 IdP 默认包含这些断言，但有些（例如 Okta）必须进行配置才能包含它们。

通常，您需要将这些用户属性（名字、姓氏和电子邮件）粘贴到标记为“名称”、“属性”或“参数”的字段中。

如果您允许用户编辑他们的电子邮件地址：请确保更新 Metabase 中相应的账户电子邮件。保持电子邮件地址同步将保护用户免于失去对其账户的访问权限。

签名 SSO 请求的设置（可选）

这些是您可以填写的附加设置，用于对 SSO 请求进行签名，以确保它们不被篡改。

在 Metabase 中启用 SAML 认证

Metabase 现在需要了解有关您的 IdP 的一些信息。以下是每个设置的明细

SAML 身份提供商 URL

Metabase 将把登录请求重定向到身份提供商 URL，用户将在那里登录 SSO。

不同的 IdP 对身份提供商 URL 使用不同的名称。以下是一些常见示例

SAML 身份提供商颁发者

SAML 身份提供商颁发者是 IdP 的唯一标识符。您也可能看到“颁发者”被称为“实体 ID”。IdP 的断言将包含此信息，Metabase 将验证颁发者是否与您设置的值匹配。

我们建议您设置此值，以使您的 SAML 配置更安全。

SAML 身份提供商证书

SAML 身份提供商证书是 Metabase 在连接到 IdP URI 时将使用的编码证书。证书看起来会是一大块文本，您需要仔细复制和粘贴——空格很重要！

您的 IdP 可能会让您将此证书下载为文件（通常是 .cer 或 .pem），然后您需要用文本编辑器打开它来复制内容，然后粘贴到 Metabase 的框中。

请注意，您的证书文本可能包含类似 -----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 的标题和页脚注释。在将证书文本粘贴到 Metabase 时，应包含这些注释。

签名 SSO 请求的设置（可选）

要对请求进行签名，以防止其被篡改，您需要提供其他设置。

如果您的 IdP 加密 SAML 响应，您需要确保此部分已填写。

如果您在初始设置期间或编辑现有值后更改了这些设置中的任何一个，您将需要重新启动 Metabase，因为密钥库文件的读取方式如此。

• SAML 密钥库路径：用于签名 SAML 请求的密钥库文件的绝对路径。
• SAML 密钥库密码：打开密钥库的魔咒。
• SAML 密钥库别名：Metabase 应用于签名 SAML 请求的密钥的别名。

SAML 单点登出 (SLO)

Metabase 支持 SAML 的单点登出 (SLO)。

SLO 的端点：/auth/sso/handle_slo

因此，如果您的 Metabase 运行在 metabase.example.com，那么登出服务 POST 绑定 URL 将是

https://metabase.example.com/auth/sso/handle_slo

启用 SAML SLO

SLO 在 Metabase 界面中是不可配置的。要启用它，您需要在 Metabase 配置文件的环境变量或 Metabase 配置文件中设置以下选项

• MB_SAML_SLO_ENABLED 为 true；
• MB_SAML_IDENTITY_PROVIDER_URI 设置为您的 IdP 的 SLO 端点；
• MB_SESSION_COOKIE_SAMESITE 设置为 none。

为了让 MB_SESSION_COOKIE_SAMESITE 设置能与 none 一起正常工作，Metabase 必须通过 HTTPS 提供服务。像 Chrome 这样的浏览器在跨站点请求中会阻止 Cookie，如果未启用 SSL。没有 HTTPS，来自您的 IdP（例如 Okta）的登出请求将不包含会话 Cookie，这意味着 Metabase 将无法正确结束会话。

将组成员资格与您的 IdP 同步

此设置允许您根据 IdP 中用户的属性将用户分配到 Metabase 组。此设置可能与您的 IdP 提供的组功能不相关；您可能需要创建一个单独的用户属性来设置用户的 Metabase 组，例如 metabaseGroups。

首先，您需要创建一个 SAML 用户属性，您将使用它来指示用户应属于哪些 Metabase 组。创建的用户属性可以是 XML 字符串或 XML 字符串列表。不同的 IdP 处理此问题的方式不同，但您很可能需要编辑用户配置文件或找到一种方法将用户的组映射到 Metabase 组名称列表。

在 Metabase 中配置组架构

在您的 SAML 提供商中设置好所有内容后，您需要在 Metabase 中配置组架构。

1. 打开“同步组隶属关系”设置。
2. 点击“编辑映射”。
3. 点击“创建映射”。
4. 输入您在 metabaseGroups 属性值中输入的组名之一，然后点击“添加”按钮。
5. 点击“组”标题下出现的下拉菜单，选择拥有此特定 metabaseGroups 值的用户应被添加到 Metabase 组。
6. 点击保存。
7. 之后，在“组属性名称”字段中输入您在 SAML 提供商中添加的用户属性的名称。在此示例中，我们告诉 Okta metabaseGroups 属性应命名为 MetabaseGroupName，因此我们将在 Metabase 的“组属性名称”字段中输入该名称。

使用 SSO 创建 Metabase 账户

付费计划 按每个附加账户收费。

新的 SSO 登录将自动创建一个新的 Metabase 账户。

通过外部身份提供商登录创建的 Metabase 账户没有密码。使用 IdP 注册 Metabase 的用户必须继续使用 IdP 登录 Metabase。

禁用密码登录

避免将自己锁在 Metabase 之外！关闭密码登录适用于所有 Metabase 账户，包括您的 Metabase 管理员账户。在关闭密码登录之前，请确保您可以通过 SSO 登录到您的管理员账户。

要*强制*用户通过 SSO 登录，请在“管理设置”>“认证”中禁用密码认证。关闭“启用密码认证”切换开关。

新账户通知电子邮件

当用户首次通过 SSO 登录 Metabase 时，Metabase 将自动为他们创建一个账户，这将触发发送给 Metabase 管理员的电子邮件通知。如果您不希望收到这些通知，请转到“管理设置”>“认证”>“用户配置”，然后关闭“通过 SSO 配置新用户的管理员通知”选项。

使用 SAML 的示例代码

您可以在 SSO 示例存储库中找到使用 SAML 认证的示例代码。

SAML 问题排查

• SAML 问题排查.