配置 Keycloak OAuth2 认证

Keycloak OAuth2 认证允许用户使用他们的 Keycloak 凭据登录 Grafana。本指南介绍了如何在 Grafana 中将 Keycloak 设置为认证提供商。

有关此提供商可用的额外配置选项，请参阅通用 OAuth 认证。

注意
如果用户在 Keycloak 中使用的电子邮件地址与他们在其他认证提供商（如 Grafana.com）中使用的电子邮件地址相同，您需要进行额外的配置以确保用户正确匹配。请参阅使用相同的电子邮件地址通过不同的身份提供商登录文档以获取更多信息。

您可能需要设置 [server] 的 root_url 选项，以确保回调 URL 正确。例如，当您在代理后面提供 Grafana 服务时。

配置示例

[auth.generic_oauth]
enabled = true
name = Keycloak-OAuth
allow_sign_up = true
client_id = YOUR_APP_CLIENT_ID
client_secret = YOUR_APP_CLIENT_SECRET
scopes = openid email profile offline_access roles
email_attribute_path = email
login_attribute_path = username
name_attribute_path = full_name
auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth
token_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/token
api_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/userinfo
role_attribute_path = contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'

例如，<PROVIDER_DOMAIN> 可以是 keycloak-demo.grafana.org，<REALM_NAME> 可以是 grafana。

要为 Keycloak 配置 kc_idp_hint 参数，您需要更改 auth_url 配置以包含 kc_idp_hint 参数。例如，如果您想提示 Google 身份提供商

auth_url = https://<PROVIDER_DOMAIN>/realms/<REALM_NAME>/protocol/openid-connect/auth?kc_idp_hint=google

注意
如果 id_token 包含所有必要的用户信息，则不需要 api_url，并且可能会增加登录过程的延迟。它可以用作备用方案，或者在用户拥有超过 150 个组成员身份时很有用。

Keycloak 配置

在 Keycloak 中创建一个客户端，设置如下

客户端 ID: grafana-oauth
已启用: ON
客户端协议: openid-connect
访问类型: confidential
标准流已启用: ON
隐式流已启用: OFF
直接访问授权已启用: ON
根 URL: <grafana_root_url>
有效重定向 URI: <grafana_root_url>/login/generic_oauth
Web 源: <grafana_root_url>
Admin URL: <grafana_root_url>
Base URL: <grafana_root_url>

例如，<grafana_root_url> 可以是 https://play.grafana.org。未列出的配置选项可以保留其默认值。

在客户端范围配置中，分配的默认客户端范围 应匹配

email
offline_access
profile
roles

警告
这些范围不会将组声明添加到 id_token。没有组声明，团队同步将无法工作。本文档后面会进一步介绍团队同步。

为了使角色映射与上述示例配置一起工作，您需要创建以下角色并将它们分配给用户

admin
editor
viewer

团队同步

注意
在 Grafana Enterprise 和 Grafana Cloud 中可用。

团队同步是一项功能，允许您将身份提供商中的组映射到 Grafana 团队。如果您想根据用户的组员身份授予他们访问特定仪表盘或文件夹的权限，这项功能非常有用。

要启用团队同步，您需要在 Keycloak 的客户端配置中添加一个 groups 映射器。这将把 groups 声明添加到 id_token 中。然后您可以使用 groups 声明将组映射到 Grafana 中的团队。

在客户端配置中，前往 Mappers 并创建一个映射器，设置如下

名称: Group Mapper
映射器类型: Group Membership
令牌声明名称: groups
完整组路径: OFF
添加到 ID 令牌: ON
添加到访问令牌: OFF
添加到用户信息: ON

在 Grafana 的配置中添加以下选项

[auth.generic_oauth]
groups_attribute_path = groups

如果您使用包含特殊字符（如引号或冒号）的嵌套组，JMESPath 解析器可以执行无害的反向函数，以便 Grafana 可以正确评估嵌套组。以下示例显示了一个名为 Global 的父组，其中包含一个嵌套组 department，该组包含一个组列表

[auth.generic_oauth]
groups_attribute_path = reverse("Global:department")

启用单点注销

要启用单点注销，您需要在 Grafana 的配置中添加以下选项

[auth.generic_oauth]
signout_redirect_url = https://<PROVIDER_DOMAIN>/auth/realms/<REALM_NAME>/protocol/openid-connect/logout?post_logout_redirect_uri=https%3A%2F%2F<GRAFANA_DOMAIN>%2Flogin

例如，<PROVIDER_DOMAIN> 可以是 keycloak-demo.grafana.org，<REALM_NAME> 可以是 grafana，<GRAFANA_DOMAIN> 可以是 play.grafana.org。

注意
Grafana 支持单点注销的 ID 令牌提示。如果 Grafana 检测到 OAuth 作为认证方法，它会自动将 id_token_hint 参数添加到注销请求中。

允许分配 Grafana Admin

如果 Grafana 收到的应用程序角色是 GrafanaAdmin，Grafana 会授予用户服务器管理员权限。

如果您想授予部分用户服务器管理员权限，这会很有用。Grafana 还会将用户分配为默认组织的 Admin 角色。

role_attribute_path = contains(roles[*], 'grafanaadmin') && 'GrafanaAdmin' || contains(roles[*], 'admin') && 'Admin' || contains(roles[*], 'editor') && 'Editor' || 'Viewer'
allow_assign_grafana_admin = true