基于 SAML 的身份验证

将您的 SSO 与 Metabase 集成允许您

• 当有人登录 Metabase 时，为其配置 Metabase 账户。
• 自动将用户属性从您的 SSO 传递到 Metabase，以实现行和列安全。
• 让人们无需重新身份验证即可访问 Metabase。

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

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

在 Metabase 中使用您的 IdP 设置 SAML

在您确认您的 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，您将使用

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

作为您的 IdP 的 SAML 表单中的重定向 URL。

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

用户属性

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

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

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

如果您允许人们编辑他们的电子邮件地址：请务必更新 Metabase 中相应的账户电子邮件。保持电子邮件地址同步将保护人们免受丢失账户访问权限的风险。

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

这些是您可以填写的额外设置，用于签署 SSO 请求以确保它们不被篡改。

在 Metabase 中启用 SAML 身份验证

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

SAML 身份提供商 URL

Metabase 会将登录请求重定向到身份提供商 URL，人们将前往该 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 配置文件设置以下选项

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

为了使 MB_SESSION_COOKIE_SAMESITE 设置与 none 一起工作，Metabase 必须通过 HTTPS 提供。如果未启用 SSL，Chrome 等浏览器将阻止跨站点请求中的 cookie。如果没有 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. 点击 Groups 标题下方出现的下拉菜单，选择具有此特定 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 问题排查.