文档 Grafana 文档 设置 配置安全性 配置身份验证 SAML

使用配置文件配置 SAML 身份验证

SAML 身份验证集成允许您的 Grafana 用户使用外部 SAML 2.0 身份提供程序 (IdP) 登录。为了实现此功能，Grafana 在身份验证流程中充当服务提供程序 (SP)，与 IdP 交互以交换用户信息。

您可以通过以下任一方法在 Grafana 中配置 SAML 身份验证

• Grafana 配置文件
• API（参考SSO 设置 API）
• 用户界面（参考使用 Grafana 用户界面配置 SAML 身份验证）
• Terraform provider（参考Terraform 文档）

所有方法提供相同的配置选项。但是，如果您希望将所有 Grafana 身份验证设置集中管理，请使用 Grafana 配置文件或 Terraform provider。如果您是 Grafana Cloud 用户，则无法访问 Grafana 配置文件。此时，请通过其他方法配置 SAML。

支持的 SAML

以下列出了 Grafana 支持的内容。

绑定

Grafana 支持以下 SAML 2.0 绑定

• 从服务提供程序 (SP) 到身份提供程序 (IdP)

  • HTTP-POST 绑定
  • HTTP-Redirect 绑定

• 从身份提供程序 (IdP) 到服务提供程序 (SP)

  • HTTP-POST 绑定

安全性

Grafana 支持签名和加密的断言，但不支持加密的请求。

初始化

Grafana 支持

• SP 发起的请求
• IdP 发起的请求

默认情况下，SP 发起的请求处于启用状态。有关如何启用 IdP 发起的登录的说明，请参考IdP 发起的单点登录 (SSO)。

在 Grafana 配置文件中编辑 SAML 选项

1. 在 Grafana 配置文件的 [auth.saml] 部分中，将enabled 设置为 true。
2. 可选地，配置证书和私钥。
3. 在创建应用程序后重定向到的 Okta 应用程序页面上，导航到“登录 (Sign On)”选项卡，并在“设置 (Settings)”部分找到“身份提供程序元数据 (Identity Provider metadata)”链接。
4. 将idp_metadata_url 设置为上一步获取的 URL。URL 应该类似于 https://<your-org-id>.okta.com/app/<application-id>/sso/saml/metadata。
5. 将以下选项设置为在 SAML 集成设置的第 10 步中配置的属性名称。您可以在应用程序页面的“常规 (General)”选项卡（“SAML 设置 (SAML Settings)”部分中的“ATTRIBUTE STATEMENTS”和“GROUP ATTRIBUTE STATEMENTS”）中找到这些属性。
   • assertion_attribute_login
   • assertion_attribute_email
   • assertion_attribute_name
   • assertion_attribute_groups
6. 可选地，在 Grafana 配置文件的 [auth.saml] 部分设置 name 参数。此参数将替换 Grafana 用户界面中（例如登录按钮）的 SAML 文本。
7. 保存配置文件，然后重启 Grafana 服务器。

完成配置后，Grafana 配置可能如下例所示

ini 复制

[server]
root_url = https://grafana.example.com

[auth.saml]
enabled = true
name = My IdP
auto_login = false
private_key_path = "/path/to/private_key.pem"
certificate_path = "/path/to/certificate.cert"
idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata"
assertion_attribute_name = DisplayName
assertion_attribute_login = Login
assertion_attribute_email = Email
assertion_attribute_groups = Group

在 Grafana 中启用 SAML 身份验证

要使用 SAML 集成，请在 grafana.ini 或 custom.ini 文件的 auth.saml 部分中，将 enabled 设置为 true。

有关配置 Grafana 的更多信息，请参考配置。

HTTP-Post 绑定的附加配置

如果身份提供程序 (IdP) 支持多种 SAML 单点登录 (SSO) 绑定，Grafana 默认使用 HTTP-Redirect 绑定。如果 IdP 仅支持 HTTP-Post binding，则可能需要更新 content_security_policy_template（如果 content_security_policy = true）和 content_security_policy_report_only_template（如果 content_security_policy_report_only = true），以允许 Grafana 向 IdP 发起 POST 请求。这些设置用于定义 Grafana 发送的 内容安全策略 (CSP) 头。

为了允许 Grafana 向 IdP 发起 POST 请求，请更新 Grafana 配置文件中的 content_security_policy_template 和 content_security_policy_report_only_template 设置，并将 IdP 的域名添加到 form-action 指令中。默认情况下，form-action 指令设置为 self，这仅允许向与 Grafana 同一域名发起 POST 请求。要允许向 IdP 的域名发起 POST 请求，请更新 form-action 指令以包含 IdP 的域名，例如：form-action 'self' https://idp.example.com。

证书和私钥

通常，证书和密钥嵌入在IDP 元数据中，并由 Grafana 根据需要自动刷新。但是，如果您的 IdP 需要签名请求，则必须提供证书和私钥。

SAML SSO 标准使用非对称加密在 SP (Grafana) 和 IdP 之间交换信息。要执行此类加密，您需要公钥和私钥。在这种情况下，X.509 证书提供公钥部分，而私钥提供私钥部分。私钥需要以PKCS#8 格式颁发。

如果您直接提供证书和密钥，Grafana 支持两种指定 certificate 和 private_key 的方式

• 不带后缀（certificate 或 private_key）时，配置假定您提供了经过 base64 编码的文件内容。
• 带有 _path 后缀（certificate_path 或 private_key_path）时，Grafana 将输入的值视为文件路径，并尝试从文件系统读取该文件。

始终与您公司的安全团队协作设置证书和私钥。如果您需要自己生成它们（例如短期测试等），请使用以下示例生成您的证书和私钥，其中包括确保密钥以 PKCS#8 格式生成。

SAML 身份验证私钥生成示例

一个示例，展示如何生成有效期为一年的自签名证书和私钥

sh 复制

$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes​

对 cert.pem 和 key.pem 文件进行 Base64 编码：（在 Mac 上不需要 -w0 参数，仅 Linux 需要）

sh 复制

$ base64 -i key.pem -o key.pem.base64
$ base64 -i cert.pem -o cert.pem.base64

然后将 base64 编码的值（key.pem.base64、cert.pem.base64 文件）用于证书和私钥。

您提供的密钥应类似于

复制

-----BEGIN PRIVATE KEY-----
...
...
-----END PRIVATE KEY-----

使用 Azure AD 设置 SAML

Grafana 支持通过 Azure AD 进行用户身份验证，当您希望用户使用单点登录访问 Grafana 时，此功能非常有用。本主题将向您展示如何在 Grafana 中使用 Azure AD 配置 SAML 身份验证。

开始之前

确保您有权管理 SAML 身份验证。有关 Grafana 中角色和权限的更多信息，请参考角色和权限。

了解 [Azure AD SAML 集成的限制] ( https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#groups-overage-claim)。

配置与 Azure AD 的 SAML 集成，首先在 Azure AD 组织内部创建一个企业应用程序，然后启用单点登录。

如果您有用户所属的组超过 150 个，请配置一个已注册的应用程序以提供 Azure Graph API 来检索组。参考设置 Azure AD Graph API 应用程序。

生成自签名证书

Azure AD 需要证书来签署 SAML 请求。您可以使用以下命令生成自签名证书

sh 复制

$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

这将生成 key.pem 和 cert.pem 文件，您可以将其用于 private_key_path 和 certificate_path 配置选项。

从图库添加 Microsoft Entra SAML Toolkit

摘自https://learn.microsoft.com/en-us/entra/identity/saas-apps/saml-toolkit-tutorial#add-microsoft-entra-saml-toolkit-from-the-gallery

1. 前往Azure 门户 并使用您的 Azure AD 帐户登录。
2. 搜索“企业应用程序 (Enterprise Applications)”。
3. 在“企业应用程序 (Enterprise applications)”窗格中，选择“新应用程序 (New application)”。
4. 在搜索框中，输入 SAML Toolkit，然后从结果面板中选择“Microsoft Entra SAML Toolkit”。
5. 添加描述性名称，然后选择“创建 (Create)”。

配置 SAML Toolkit 应用程序端点

为了使用 Grafana 验证 Azure AD 用户，您需要在 Azure AD 组织中创建新的 SAML 集成，以配置 SAML Toolkit 应用程序端点。

对于以下配置，我们将使用 https:// 作为 Grafana URL。请将其替换为您的 Grafana URL。

1. 在“SAML Toolkit 应用程序 (SAML Toolkit application)”中，选择“设置单点登录 (Set up single sign-on)”。
2. 在“单点登录 (Single sign-on)”窗格中，选择“SAML”。
3. 在“使用 SAML 设置单点登录 (Set up Single Sign-On with SAML)”窗格中，选择“基本 SAML 配置 (Basic SAML Configuration)”旁的铅笔图标以编辑设置。
4. 在“基本 SAML 配置 (Basic SAML Configuration)”窗格中，点击“编辑 (Edit)”按钮并更新以下字段
   • 在“标识符 (Entity ID)”字段中，输入 https:///saml/metadata。
   • 在“回复 URL (Assertion Consumer Service URL)”字段中，输入 https:///saml/acs。
   • 在“登录 URL (Sign on URL)”字段中，输入 https://。
   • 在“Relay State”字段中，输入 https://。
   • 在 Logout URL 字段中，输入 https:///saml/slo。
5. 选择 保存。
6. 在 SAML Certificate 部分，复制 App Federation Metadata Url。
   • 在 custom.ini 文件中的 idp_metadata_url 字段中使用此 URL。

在 Azure AD 中配置 Graph API 应用程序

虽然可以在 Grafana 中通过 SAML 配置 Azure AD 租户，但某些附加信息只能通过 Graph API 访问。要检索此信息，请在 Azure AD 中创建一个新应用程序并授予必要的权限。

Azure AD SAML 限制

对于以下配置，URL https:// 将用作 Grafana URL。请将其替换为您的 Grafana 实例 URL。

创建新的应用程序注册

此应用程序注册将用作服务帐户，用于从 Azure AD 检索有关用户的更多信息。

1. 前往Azure 门户 并使用您的 Azure AD 帐户登录。
2. 在左侧导航窗格中，选择 Azure Active Directory 服务，然后选择 App registrations。
3. 单击 New registration 按钮。
4. 在 Register an application 窗格中，输入应用程序的名称。
5. 在 Supported account types 部分，选择可以使用应用程序的帐户类型。
6. 在 Redirect URI 部分，选择 Web 并输入 https:///login/azuread。
7. 单击 Register 按钮。

设置应用程序的权限

1. 在概览窗格中，查找 API permissions 部分并选择 Add a permission。
2. 在 Request API permissions 窗格中，选择 Microsoft Graph，然后单击 Application permissions。
3. 在 Select permissions 窗格中，在 GroupMember 部分下，选择 GroupMember.Read.All。
4. 在 Select permissions 窗格中，在 User 部分下，选择 User.Read.All。
5. 单击页面底部的 Add permissions 按钮。
6. 在 Request API permissions 窗格中，选择 Microsoft Graph，然后单击 Delegated permissions。
7. 在 Select permissions 窗格中，在 User 部分下，选择 User.Read。
8. 单击页面底部的 Add permissions 按钮。
9. 在 API permissions 部分，选择 Grant admin consent for 。

下表显示了从 Azure AD 门户看到的权限

生成客户端密钥

1. 在 Overview 窗格中，选择 Certificates & secrets。
2. 选择 New client secret。
3. 在 Add a client secret 窗格中，输入密钥的描述。
4. 设置密钥的过期日期。
5. 选择 Add。
6. 复制密钥的值。此值用于 custom.ini 文件中的 client_secret 字段。

使用 Okta 设置 SAML

Grafana 支持通过 Okta 进行用户认证，当您希望用户使用单点登录访问 Grafana 时，这非常有用。本指南将引导您完成在 Grafana 中使用 Okta 配置 SAML 认证的步骤。您需要在 Okta 组织中拥有管理员权限才能访问 Admin Console 并创建 SAML 集成。您还需要编辑 Grafana 配置文件和重新启动 Grafana 服务器的权限。

开始之前

• 要配置与 Okta 的 SAML 集成，请首先在 Okta 组织内创建一个应用程序集成。在 Okta 中添加应用程序集成
• 确保您有权管理 SAML 身份验证。有关 Grafana 中角色和权限的更多信息，请参考角色和权限。

设置 Okta SAML

1. 登录 Okta 门户。

2. 通过单击右上角的 Admin 进入 Okta 组织中的 Admin Console。如果您位于 Developer Console 中，请单击左上角的 Developer Console，然后单击 Classic UI 切换到 Admin Console。

3. 在 Admin Console 中，导航到 Applications > Applications。

4. 单击 Create App Integration 启动应用程序集成向导。

5. 选择 SAML 2.0 作为 Sign-in method。

6. 单击 Create。

7. 在 **General Settings* * 选项卡上，输入 Grafana 集成的名称。您还可以上传徽标。

8. 在 **Configure SAML* * 选项卡上，输入与您的 Grafana 实例相关的 SAML 信息

   • 在 Single sign on URL 字段中，使用您的 Grafana 实例的 /saml/acs 端点 URL，例如 https://grafana.example.com/saml/acs。

   • 在 Audience URI (SP Entity ID) 字段中，使用 /saml/metadata 端点 URL，默认情况下它是您的 Grafana 实例的 /saml/metadata 端点（例如 https://example.grafana.com/saml/metadata）。这可以配置为不同，但此处的值必须与 Grafana 的 SAML 设置的 entity_id 设置匹配。

   • 保留 **Name ID format* * 和 **Application username* * 的默认值。

     注意

      If you plan to enable SAML Single Logout, consider setting the **Name ID format** to `EmailAddress` or `Persistent`. This must match the `name_id_format` setting of the Grafana instance.
     

   • 在 ATTRIBUTE STATEMENTS (OPTIONAL) 部分，输入要与 Grafana 共享的 SAML 属性。Okta 中的属性名称需要与 Grafana 中定义的完全匹配，例如

     属性名称（在 Grafana 中）	名称和值（在 Okta 配置文件中）	Grafana 配置（在 auth.saml 下）
     Login	Login - user.login	assertion_attribute_login = Login
     电子邮件	Email - user.email	assertion_attribute_email = Email
     DisplayName	DisplayName - user.firstName + " " + user.lastName	assertion_attribute_name = DisplayName

   • 在 GROUP ATTRIBUTE STATEMENTS (OPTIONAL) 部分，输入组属性名称（例如 Group，确保它与 Grafana 中的 asssertion_attribute_groups 设置匹配）并设置过滤器为 Matches regex .* 以返回所有用户组。

9. 单击 Next。

10. 在最终的 Feedback 选项卡上，填写表格，然后单击 **Finish* *。

签名算法

SAML 标准建议对某些类型的消息（如认证或注销请求）使用数字签名。如果配置了 signature_algorithm 选项，Grafana 会在 SAML 请求中放入数字签名。支持的签名类型有 rsa-sha1、rsa-sha256、rsa-sha512。此选项应与您的 IdP 配置匹配，否则签名验证将失败。Grafana 使用通过 private_key 和 certificate 选项配置的密钥和证书来签署 SAML 请求。

指定用户的 Name ID

name_id_format 配置字段指定 SAML assertion 中 NameID 元素的格式。

默认情况下，此项设置为 urn:oasis:names:tc:SAML:2.0:nameid-format:transient，无需在配置文件中指定。

以下列表包含有效的配置字段值

IdP 元数据

您还需要定义 IdP 的公共部分用于消息验证。SAML IdP 元数据 XML 定义了 Grafana 在何处以及如何交换用户信息。

Grafana 支持三种指定 IdP 元数据的方式。

• 如果没有后缀 idp_metadata，Grafana 假定是 base64 编码的 XML 文件内容。
• 如果带有 _path 后缀，Grafana 假定是文件路径，并尝试从文件系统读取文件。
• 如果带有 _url 后缀，Grafana 假定是 URL，并尝试从给定位置加载元数据。

最大签发延迟

防止 SAML 响应重放攻击以及 SP (Grafana) 和 IdP 之间的内部时钟偏差。您可以设置 IdP 签发响应到 SP (Grafana) 处理响应之间的最大时间量。

配置选项指定为持续时间，例如 max_issue_delay = 90s 或 max_issue_delay = 1h。

元数据有效期

SP 元数据可能在某个时间点过期，可能是由于证书轮换或位置绑定更改。Grafana 允许您指定元数据应有效多久。利用 validUntil 字段，您可以告诉消费者您的元数据何时会失效。持续时间是通过将持续时间添加到当前时间来计算的。

配置选项指定为持续时间，例如 metadata_valid_duration = 48h。

身份提供商 (IdP) 注册

为了使 SAML 集成正常工作，您需要让 IdP 知道 SP。

集成提供两个关键的 Grafana 端点

• /saml/metadata 端点，其中包含 SP 元数据。您可以手动下载并上传，或者让 IdP 直接从该端点请求。一些提供商将其命名为 Identifier 或 Entity ID。
• /saml/acs 端点，用于接收 ACS (Assertion Customer Service) 回调。一些提供商将其命名为 SSO URL 或 Reply URL。

IdP 发起的单点登录 (SSO)

默认情况下，Grafana 仅允许服务提供商 (SP) 发起的登录（当用户通过 Grafana 的登录页面使用 SAML 登录时）。如果您希望用户直接从您的身份提供商 (IdP) 登录 Grafana，请将 allow_idp_initiated 配置选项设置为 true，并将 relay_state 配置为与 IdP 配置中指定的值相同。

IdP 发起的 SSO 存在一些安全风险，因此在启用此功能之前请确保您了解这些风险。使用 IdP 发起的 SSO 时，Grafana 会收到未经请求的 SAML 请求，无法验证登录流程是否由用户启动。这使得难以检测 SAML 消息是否被盗用或替换。正因如此，IdP 发起的 SSO 容易受到登录跨站点请求伪造 (CSRF) 和中间人 (MITM) 攻击。我们不建议使用 IdP 发起的 SSO，并尽可能保持其禁用状态。

单点注销

SAML 的单点注销功能允许用户从通过 SAML SSO 建立的当前 IdP 会话相关联的所有应用程序中注销。如果 single_logout 选项设置为 true 并且用户注销，Grafana 会请求 IdP 结束用户会话，这反过来会触发用户使用同一 IdP 会话登录的所有其他应用程序的注销（应用程序应支持单点注销）。反之，如果连接到同一 IdP 的另一个应用程序使用单点注销注销，Grafana 会收到来自 IdP 的注销请求并结束用户会话。

单点注销支持 HTTP-Redirect 和 HTTP-POST 绑定。使用 HTTP-Redirect 绑定时，查询应包含请求签名。

配置单点注销

在 Grafana 中配置单点注销

1. 在配置中启用 single_logout 选项。
2. 确保 name_id_format 与您的 IdP 期望的格式匹配（例如，urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress）。
3. 启用 improvedExternalSessionHandlingSAML 功能开关以获得完整的 NameID 和 SessionIndex 支持（Grafana v11.5+）。
4. 启用此功能后，用户可能需要再次登录以建立新会话。

Grafana v11.5 中的 NameID 和 SessionIndex 更改

在 Grafana 11.5 版本之前，Login 属性值（使用 assertion_attribute_login 配置从 SAML assertion 中提取）被用作注销请求中的 NameID。如果 assertion_attribute_login 值与身份提供商 (IdP) 期望的值不同，这可能会导致单点注销出现问题。

此外，Grafana 不支持 IdP 会话，无法在注销请求中包含 SessionIndex（IdP 侧用户会话的唯一标识符）值。这可能导致用户从 Grafana 注销时，从其所有应用程序/IdP 会话中注销的问题。

从 Grafana 11.5 版本开始，Grafana 使用 SAML assertion 中的 NameID 来创建注销请求。如果 assertion 中不存在 NameID，Grafana 默认为使用用户的 Login 属性。此外，如果 IdP 在 SAML assertion 中提供了 SessionIndex，Grafana 支持在注销请求中包含 SessionIndex。

Assertion 映射

在 SAML SSO 认证流程中，Grafana 接收 ACS 回调。回调包含嵌入在 SAML 响应中的所有经过认证用户的相关信息。Grafana 解析响应以在其内部数据库中创建（或更新）用户。

Grafana 映射用户信息时，它会查看 assertion 中的各个属性。您可以将这些属性视为键/值对（尽管它们包含的信息比这更多）。

Grafana 提供配置选项，允许您修改查找这些值的键。我们在 Grafana 中创建用户所需的数据是姓名、登录句柄和电子邮件。

assertion_attribute_name 选项

assertion_attribute_name 是一种特殊的 assertion 映射，它可以是一个简单的键，表示映射到 SAML 响应上的单个 assertion 属性，或者是一个使用 $__saml{<attribute>} 语法的包含变量的复杂模板。如果此属性配置错误，Grafana 将在启动时记录错误消息并禁止 SAML 登录。如果在登录尝试后，模板中的变量在 SAML 响应中缺失，Grafana 也会记录错误。

示例

ini 复制

#plain string mapping
assertion_attribute_name = displayName

ini 复制

#template mapping
assertion_attribute_name = $__saml{firstName} $__saml{lastName}

允许新用户注册

默认情况下，使用 SAML 认证的新 Grafana 用户将自动创建帐户。要分离认证和帐户创建，并确保只有现有帐户的用户才能通过 SAML 登录，请将 allow_sign_up 选项设置为 false。

配置自动登录

将 auto_login 选项设置为 true 以尝试自动登录，跳过登录屏幕。如果多个认证提供商配置为使用自动登录，此设置将被忽略。

ini 复制

auto_login = true

配置团队同步

要使用 SAML 团队同步，请将 assertion_attribute_groups 设置为您存储用户组的属性名称。然后 Grafana 将使用从 SAML assertion 中提取的属性值将用户添加到在“外部组同步”选项卡上配置的同名组中。

给出以下部分 SAML assertion

xml 复制

<saml2:Attribute
    Name="groups"
    NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
    <saml2:AttributeValue
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="xs:string">admins_group
    </saml2:AttributeValue>
    <saml2:AttributeValue
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="xs:string">division_1
    </saml2:AttributeValue>
</saml2:Attribute>

配置如下所示

ini 复制

[auth.saml]
# ...
assertion_attribute_groups = groups

以下 External Group ID 可用于在所需团队的外部组同步选项卡中输入

• admins_group
• division_1

了解更多关于团队同步

配置角色同步

角色同步允许您将用户角色从身份提供商映射到 Grafana。要启用角色同步，请配置 Editor、Admin 和 Grafana Admin 角色的角色属性和可能值。有关用户角色的更多信息，请参阅角色和权限。

1. 在配置文件中，将 assertion_attribute_role 选项设置为从中提取角色信息的属性名称。
2. 将 role_values_none 选项设置为映射到 None 角色的值。
3. 将 role_values_viewer 选项设置为映射到 Viewer 角色的值。
4. 将 role_values_editor 选项设置为映射到 Editor 角色的值。
5. 将 role_values_admin 选项设置为映射到组织 Admin 角色的值。
6. 将 role_values_grafana_admin 选项设置为映射到 Grafana Admin 角色的值。

如果用户角色与任何已配置的值都不匹配，则将分配由 auto_assign_org_role 配置选项指定的角色。如果未设置 auto_assign_org_role 字段，则用户角色将默认为 Viewer。

有关 Grafana 中角色和权限的更多信息，请参阅角色和权限。

配置示例

ini 复制

[auth.saml]
assertion_attribute_role = role
role_values_none = none
role_values_viewer = external
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin

重要：配置角色同步后，下次用户登录时，在 Grafana 中手动对用户角色和组织成员资格所做的任何更改都将被覆盖。请改在 IdP 中分配用户组织和角色。

如果您不想将用户组织和角色与 IdP 同步，可以使用 skip_org_role_sync 配置选项。

配置示例

ini 复制

[auth.saml]
skip_org_role_sync = true

配置组织映射

组织映射允许您根据从身份提供商获取的属性值，将用户分配到 Grafana 中的特定组织。

1. 在配置文件中，将 assertion_attribute_org 设置为您存储组织信息的属性名称。如果您希望用户属于多个组织，此属性可以是数组。
2. 将 org_mapping 选项设置为逗号分隔的 Organization:OrgId 对列表，用于将 IdP 中的组织映射到由 ID 指定的 Grafana 组织。如果您希望用户在多个组织中拥有不同的角色，可以将此选项设置为逗号分隔的 Organization:OrgId:Role 映射列表。

例如，以下配置根据 Org assertion 属性值，将 Engineering 组织的用户分配到 ID 为 2 的 Grafana 组织作为 Editor，将 Sales 的用户分配到 ID 为 3 的组织作为 Admin

ini 复制

[auth.saml]
assertion_attribute_org = Org
org_mapping = Engineering:2:Editor, Sales:3:Admin

从 Grafana 11.5 版本开始，您可以在 org_mapping 选项中使用组织名称而不是组织 ID。确保您配置的组织名称与 Grafana 中的组织名称完全匹配，因为它区分大小写。如果在 Grafana 中找不到组织名称，则将忽略该映射。如果外部组织或组织名称包含空格，请对 org_mapping 选项使用 JSON 语法

ini 复制

org_mapping = ["Org 1:2:Editor", "ExternalOrg:ACME Corp.:Admin"]

如果其中一个映射包含 :，请使用 JSON 语法并用反斜杠转义 :

ini 复制

# Assign users from "External:Admin" to the organization with name "ACME Corp" as Admin
org_mapping = ["External\:Admin:ACME Corp:Admin"]

例如，根据 Org assertion 属性值，将 Engineering 组织的用户分配到名称为 ACME Corp 的 Grafana 组织作为 Editor，将 Sales 的用户分配到 ID 为 3 的组织作为 Admin

ini 复制

[auth.saml]
assertion_attribute_org = Org
org_mapping = ["Engineering:ACME Corp:Editor", "Sales:3:Admin"]

您可以为 IdP 和 Grafana 指定多个组织

• org_mapping = Engineering:2, Sales:2 用于将来自 Engineering 和 Sales 的用户映射到 Grafana 中的 2。
• org_mapping = Engineering:2, Engineering:3 用于将 Engineering 分配到 Grafana 中的 2 和 3。

如果您希望所有用户都拥有默认角色并属于某些 Grafana 组织，可以使用 * 作为 SAML Organization

• org_mapping = *:2:Editor 用于将所有用户映射到 Grafana 中的 2 作为 Editors。

如果您希望给定 SAML 组织中的所有用户都添加到所有现有 Grafana 组织中，可以在映射中使用 * 作为 Grafana 组织。

• org_mapping = Engineering:* 用于将来自 Engineering 的用户映射到所有现有 Grafana 组织。
• org_mapping = Administration:*:Admin 用于将来自 Administration 的用户映射到所有现有 Grafana 组织作为 Admins。

配置允许的组织

使用 allowed_organizations 选项，您可以指定用户必须至少属于其中一个组织才能登录 Grafana 的组织列表。

要在列表中放入包含空格的值，请使用以下 JSON 语法

ini 复制

allowed_organizations = ["org 1", "second org"]

SAML 配置示例

ini 复制

[auth.saml]
enabled = true
auto_login = false
certificate_path = "/path/to/certificate.cert"
private_key_path = "/path/to/private_key.pem"
idp_metadata_path = "/my/metadata.xml"
max_issue_delay = 90s
metadata_valid_duration = 48h
assertion_attribute_name = displayName
assertion_attribute_login = mail
assertion_attribute_email = mail

assertion_attribute_groups = Group
assertion_attribute_role = Role
assertion_attribute_org = Org
role_values_viewer = external
role_values_editor = editor, developer
role_values_admin = admin, operator
role_values_grafana_admin = superadmin
org_mapping = Engineering:2:Editor, Engineering:3:Viewer, Sales:3:Editor, *:1:Editor
allowed_organizations = Engineering, Sales

Terraform 中的 SAML 配置示例

terraform 复制

resource "grafana_sso_settings" "saml_sso_settings" {
  provider_name = "saml"
  saml_settings {
    name                       = "SAML"
    auto_login                 = false
    certificate_path           = "/path/to/certificate.cert"
    private_key_path           = "/path/to/private_key.pem"
    idp_metadata_path          = "/my/metadata.xml"
    max_issue_delay            = "90s"
    metadata_valid_duration    = "48h"
    assertion_attribute_name   = "displayName"
    assertion_attribute_login  = "mail"
    assertion_attribute_email  = "mail"
    assertion_attribute_groups = "Group"
    assertion_attribute_role   = "Role"
    assertion_attribute_org    = "Org"
    role_values_editor         = "editor, developer"
    role_values_admin          = "admin, operator"
    role_values_grafana_admin  = "superadmin"
    org_mapping                = "Engineering:2:Editor, Engineering:3:Viewer, Sales:3:Editor, *:1:Editor"
    allowed_organizations      = "Engineering, Sales"
  }
}

访问 Terraform Registry 以获取使用 grafana_sso_settings 资源的完整参考。

排除 Grafana 中的 SAML 认证故障

要排除故障并获取更多日志信息，请在配置文件中启用 SAML 调试日志记录。有关更多信息，请参阅配置。

ini 复制

[log]
filters = saml.auth:debug

故障排除

以下是配置 Grafana 中的 SAML 认证时遇到的常见问题及其解决方法。

无限重定向循环 / 用户在 IdP 端成功登录后被重定向到登录页面

如果您在 auto_login = true 时遇到无限重定向循环，或者在成功登录后被重定向到登录页面，可能是由于 grafana_session cookie 的 SameSite 设置为 Strict。此设置阻止在跨站点请求期间将 grafana_session cookie 发送到 Grafana。要解决此问题，请在 Grafana 配置文件中将 security.cookie_samesite 选项设置为 Lax。

SAML 认证失败，出现错误

• asn1: structure error: tags don't match

我们仅支持一种私钥格式：PKCS#8。

密钥可能采用不同的格式（PKCS#1 或 PKCS#12）；在这种情况下，可能需要转换私钥格式。

以下命令创建 pkcs8 密钥文件。

bash 复制

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

转换私钥格式为 base64

以下命令将密钥转换为 base64 格式。

对 cert.pem 和 key.pem 文件进行 Base64 编码：（在 Mac 上不需要 -w0 开关，仅在 Linux 上需要）

sh 复制

$ base64 -w0 key.pem > key.pem.base64
$ base64 -w0 cert.pem > cert.pem.base64

然后将 Base64 编码的值（key.pem.base64, cert.pem.base64 文件）用于证书和 private_key。

您提供的密钥应如下所示

复制

-----BEGIN PRIVATE KEY-----
...
...
-----END PRIVATE KEY-----

SAML 登录尝试失败，请求响应为“源不允许”

当用户使用 SAML 登录并出现“源不允许”时，用户可能正在从 IdP（身份提供商）服务发起登录，或者用户位于反向代理后面。这可能发生在 Grafana 的 CSRF 检查认为请求无效时。有关更多信息，请参阅CSRF。

要解决此问题，您可以在 SAML 配置中配置 csrf_trusted_origins 或 csrf_additional_headers 选项。

配置文件的示例

ini 复制

# config.ini
...
[security]
csrf_trusted_origins = https://grafana.example.com
csrf_additional_headers = X-Forwarded-Host
...

SAML 登录尝试失败，请求响应为“登录会话已过期”

从不是 Grafana 服务器根 URL 的 URL 访问 Grafana 登录页面，可能导致实例返回以下错误：“登录会话已过期”。

如果您通过代理服务器访问 Grafana，请确保 cookie 已正确重写为 Grafana 的根 URL。Cookie 必须设置在与 Grafana 的 root_url 相同的 URL 上。这通常是反向代理的域/地址。

查看代理服务器配置中的 cookie 设置，确保 cookie 未被丢弃

查看 grafana 配置中的以下设置

ini 复制

[security]
cookie_samesite = none

此设置应设置为 none，以允许 grafana 会话 cookie 在重定向时正常工作。

ini 复制

[security]
cookie_secure = true

确保 cookie_secure 设置为 true，以确保 cookie 仅通过 HTTPS 发送。

在 Grafana 中配置 SAML 认证

下表描述了所有 SAML 配置选项。请继续阅读下文以了解特定选项的详细信息。与任何其他 Grafana 配置一样，您可以将这些选项作为环境变量应用。