文档 Grafana 文档 设置 配置安全性 配置身份验证 通用 OAuth

配置通用 OAuth 身份验证

Grafana 中有多种身份验证方法可用于验证用户身份。身份验证配置决定了哪些用户可以访问 Grafana 以及他们可以使用的登录方法。您还可以配置 Grafana 以基于身份验证提供程序集成返回的信息，自动更新用户在 Grafana 中的角色和团队成员资格。

在决定身份验证方法时，务必考虑您当前的身份和访问管理系统以及您需要的特定身份验证和授权功能。有关可用身份验证选项及其支持的功能的完整列表，请参阅配置身份验证。

Grafana 为以下身份验证提供程序提供 OAuth2 集成

• Azure AD OAuth
• GitHub OAuth
• GitLab OAuth
• Google OAuth
• Grafana Com OAuth
• Keycloak OAuth
• Okta OAuth

如果您的 OAuth2 提供程序未列出，则可以使用通用 OAuth 身份验证。

本主题介绍如何使用不同的方法配置通用 OAuth 身份验证，并包含使用特定 OAuth2 提供程序的通用 OAuth 设置示例。

开始之前

要遵循本指南

• 请确保您知道如何使用 OAuth2 提供程序创建 OAuth2 应用程序。有关更多信息，请查阅 OAuth2 提供程序的文档。
• 请确保您的身份提供程序返回与 OpenID UserInfo 兼容的信息，例如 sub 声明。
• 如果您正在使用刷新令牌，请确保您知道如何使用 OAuth2 提供程序设置它们。有关更多信息，请查阅 OAuth2 提供程序的文档。

使用 Grafana UI 配置通用 OAuth 身份验证客户端

作为 Grafana 管理员，您可以使用通用 OAuth UI 从 Grafana 中配置通用 OAuth 客户端。为此，请导航到管理 > 身份验证 > 通用 OAuth 页面并填写表单。如果您在 Grafana 配置文件中具有当前配置，则表单将预先填充这些值，否则表单将包含默认值。

填写完表单后，单击保存以保存配置。如果保存成功，Grafana 将应用新配置。

如果您需要将 UI 中所做的更改重置为默认值，请单击重置。重置更改后，Grafana 将应用 Grafana 配置文件中的配置（如果有任何配置）或默认值。

有关更多信息，请参阅配置选项。

使用 Terraform 提供程序配置通用 OAuth 身份验证客户端

terraform 复制

resource "grafana_sso_settings" "generic_sso_settings" {
  provider_name = "generic_oauth"
  oauth2_settings {
    name              = "Auth0"
    auth_url          = "https://<domain>/authorize"
    token_url         = "https://<domain>/oauth/token"
    api_url           = "https://<domain>/userinfo"
    client_id         = "<client id>"
    client_secret     = "<client secret>"
    allow_sign_up     = true
    auto_login        = false
    scopes            = "openid profile email offline_access"
    use_pkce          = true
    use_refresh_token = true
  }
}

有关使用 grafana_sso_settings 资源的完整参考，请参阅Terraform 注册表。

使用 Grafana 配置文件配置通用 OAuth 身份验证客户端

请确保您有权访问Grafana 配置文件。

步骤

要使用我们的通用 OAuth 身份验证将您的 OAuth2 提供程序与 Grafana 集成，请按照以下步骤操作

1. 在您选择的 OAuth2 提供程序中创建 OAuth2 应用程序。

2. 将 OAuth2 应用程序的回调 URL 设置为 http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/generic_oauth。

   确保回调 URL 是您用于通过浏览器访问 Grafana 的完整 HTTP 地址，但附加了 /login/generic_oauth 路径。

   为了使回调 URL 正确，可能需要在 Grafana 配置文件的 [server] 部分中设置 root_url 选项。例如，如果您在代理后面提供 Grafana 服务。

3. 请参阅下表以更新 Grafana 配置文件 [auth.generic_oauth] 部分中的字段值

   字段	描述
   client_id、client_secret	这些值必须与您的 OAuth2 应用程序中的客户端 ID 和客户端密钥匹配。
   auth_url	您的 OAuth2 提供程序的授权端点。
   api_url	您的 OAuth2 提供程序的用户信息端点。此端点返回的信息必须与OpenID UserInfo兼容。
   enabled	启用通用 OAuth 身份验证。将此值设置为 true。

   查看其他通用 OAuth 配置选项列表，并在必要时完成它们。

4. 可选：配置刷新令牌

   a. 使用 OAuth2 提供程序使用的刷新令牌范围扩展 Grafana 配置文件中 [auth.generic_oauth] 部分的 scopes 字段。

   b. 在 Grafana 配置文件的 [auth.generic_oauth] 部分中将 use_refresh_token 设置为 true。

   c. 如果需要，在提供程序上启用刷新令牌。

5. 配置角色映射.

6. 可选：配置组同步。

7. 重启 Grafana。

   您现在应该在登录页面上看到一个通用 OAuth 登录按钮，并且能够使用您的 OAuth2 提供程序登录或注册。

配置登录名

Grafana 可以从 OAuth2 ID 令牌或从 OAuth2 UserInfo 端点检索的用户信息中解析用户的登录名。Grafana 按列出的顺序查看这些来源，直到找到登录名。如果未找到登录名，则用户的登录名将设置为用户的电子邮件地址。

请参阅下表，了解根据您的 Oauth2 提供程序如何返回用户的登录名来配置哪些内容的信息

配置显示名称

Grafana 可以从 OAuth2 ID 令牌或从 OAuth2 UserInfo 端点检索的用户信息中解析用户的显示名称。Grafana 按列出的顺序查看这些来源，直到找到显示名称。如果未找到显示名称，则改为显示用户的登录名。

请参阅下表，了解根据您的 Oauth2 提供程序如何返回用户的姓名来配置哪些内容的信息

配置电子邮件地址

Grafana 可以从 OAuth2 ID 令牌、从 OAuth2 UserInfo 端点检索的用户信息或 OAuth2 /emails 端点解析用户的电子邮件地址。Grafana 按列出的顺序查看这些来源，直到找到电子邮件地址。如果未找到电子邮件，则用户的电子邮件地址将设置为空字符串。

请参阅下表，了解根据 Oauth2 提供程序如何返回用户的电子邮件地址来配置哪些内容的信息

当用户使用 OAuth2 提供程序登录时，Grafana 会验证访问令牌是否已过期。当访问令牌过期时，Grafana 会使用提供的刷新令牌（如果存在）来获取新的访问令牌。

Grafana 使用刷新令牌来获取新的访问令牌，而无需用户再次登录。如果刷新令牌不存在，则在访问令牌过期后，Grafana 会将用户注销系统。

要配置通用 OAuth 以使用刷新令牌，请将 use_refresh_token 配置选项设置为 true，并在必要时执行以下步骤中的一个或两个

使用其他范围扩展 Grafana 配置文件中 [auth.generic_oauth] 部分的 scopes 字段。

1. 在提供程序上启用刷新令牌。
2. 注意： accessTokenExpirationCheck 功能开关已在 Grafana v10.3.0 中移除，并且 use_refresh_token 配置值将改为用于配置刷新令牌获取和访问令牌过期检查。

除非启用 skip_org_role_sync 选项，否则用户的角色将在用户登录时设置为从身份验证提供程序检索的角色。

配置角色映射

用户的角色是使用来自 role_attribute_path 配置选项的 JMESPath 表达式检索的。要映射服务器管理员角色，请使用 allow_assign_grafana_admin 配置选项。有关更多信息，请参阅配置选项。

如果未找到有效角色，则会为用户分配 auto_assign_org_role 选项指定的角色。您可以通过设置 role_attribute_strict = true 来禁用此默认角色分配。如果在评估 role_attribute_path 和 org_mapping 表达式后未返回角色或返回无效角色，则此设置会拒绝用户访问。

您可以使用 org_attribute_path 和 org_mapping 配置选项将用户分配给组织并指定其角色。有关更多信息，请参阅组织角色映射示例。如果同时指定了组织角色映射 (org_mapping) 和常规角色映射 (role_attribute_path)，则用户将获得两个映射角色中最高的角色。

为了简化正确 JMESPath 表达式的配置，请转到 JMESPath 以测试和评估具有自定义负载的表达式。

角色映射示例

本节包含用于角色映射的 JMESPath 表达式示例。

映射用户组织角色

在此示例中，用户已被授予 Editor 角色。分配的角色基于属性 role 的值，该值必须是有效的 Grafana 角色，例如 Admin、Editor、Viewer 或 None。

负载

json 复制

{
    ...
    "role": "Editor",
    ...
}

bash 复制

role_attribute_path = role

映射服务器管理员角色

json 复制

{
    ...
    "groups": [
        "engineer",
        "admin",
    ],
    ...
}

bash 复制

role_attribute_path = contains(groups[*], 'admin') && 'Admin' || contains(groups[*], 'editor') && 'Editor' || 'Viewer'

在以下示例中，用户被授予 Grafana 服务器管理员角色。

ini 复制

json 复制

{
    ...
    "roles": [
        "admin",
    ],
    ...
}

bash 复制

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

在此示例中，所有用户都将被分配 Viewer 角色，而不管从身份提供程序收到的用户信息如何。

组织角色映射示例

bash 复制

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Org roles mapping example

在此示例中，用户已被授予 org_foo 组织中的 Viewer 角色，以及 org_bar 和 org_baz 组织中的 Editor 角色。

如果用户是 admin 组的成员，他们将被授予 Grafana 服务器管理员角色。

json 复制

{
  "roles": ["org_foo", "org_bar", "another_org"]
}

bash 复制

role_attribute_path = contains(roles[*], 'admin') && 'GrafanaAdmin' || 'None'
allow_assign_grafana_admin = true
org_attribute_path = roles
org_mapping = org_foo:org_foo:Viewer org_bar:org_bar:Editor *:org_baz:Editor

配置组同步

Grafana 支持 OAuth2 群组与 Grafana 团队和角色的同步。这允许自动将用户分配到相应的团队或自动授予他们映射的角色。团队和角色在用户登录时同步。

通用 OAuth 群组可以通过群组 ID 引用，例如 8bab1c86-8fba-33e5-2089-1d1c80ec267d 或 myteam。有关使用 groups_attribute_path 配置选项配置带有 Grafana 的 OAuth2 群组的信息，请参阅 配置选项。

要了解有关群组同步的更多信息，请参阅 配置团队同步 和 配置群组属性同步。

群组属性同步示例

配置

groups_attribute_path = groups

json 复制

{
    ...
    "groups": [
        "engineers",
        "analysts",
    ],
    ...
}

配置选项

下表概述了各种通用 OAuth 配置选项。您可以将这些选项作为环境变量应用，类似于 Grafana 中的任何其他配置。有关更多信息，请参阅 使用环境变量覆盖配置。

设置通用 OAuth 的示例

本节包含设置通用 OAuth 集成的示例。

使用 Descope 设置 OAuth2

要使用 Descope 设置通用 OAuth 身份验证，请按照以下步骤操作

1. 在此处 创建一个 Descope 项目，并完成入门向导以配置您的身份验证。如果您已经设置了 Descope 项目，则可以跳过此步骤。

2. 如果您希望使用 Sign Up or In 以外的流程，请转到控制台中的 IdP 应用程序 菜单，然后选择您的 IdP 应用程序。然后更改 流程托管 URL 查询参数 ?flow=sign-up-or-in 以更改您希望使用的流程 ID。

3. 单击 保存。

4. 使用 设置 选项卡中的值更新 Grafana 配置文件的 [auth.generic_oauth] 部分

   注意

   您可以在 项目设置 下获取您的客户端 ID（Descope 项目 ID）。您的客户端密钥（Descope 访问密钥）可以在 访问密钥 下生成。

   在以下更复杂的示例中，用户已被授予 Admin 角色。这是因为他们是其 OAuth2 提供程序的 admin 组的成员。如果用户是 editor 组的成员，他们将被授予 Editor 角色，否则为 Viewer。

   [auth.generic_oauth]
   enabled = true
   allow_sign_up = true
   auto_login = false
   team_ids =
   allowed_organizations =
   name = Descope
   client_id = <Descope Project ID>
   client_secret = <Descope Access Key>
   scopes = openid profile email descope.claims descope.custom_claims
   auth_url = https://api.descope.com/oauth2/v1/authorize
   token_url = https://api.descope.com/oauth2/v1/token
   api_url = https://api.descope.com/oauth2/v1/userinfo
   use_pkce = true
   use_refresh_token = true

使用 Auth0 设置 OAuth2

要使用 Auth0 设置通用 OAuth 身份验证，请按照以下步骤操作

1. 使用以下参数创建 Auth0 应用程序

   • 名称：Grafana
   • 类型：常规 Web 应用程序

2. 转到应用程序的 设置 选项卡，并将 允许的回调 URL 设置为 https://<grafana domain>/login/generic_oauth。

3. 单击 保存更改。

4. 使用 设置 选项卡中的值更新 Grafana 配置文件的 [auth.generic_oauth] 部分

   在以下更复杂的示例中，用户已被授予 Admin 角色。这是因为他们是其 OAuth2 提供程序的 admin 组的成员。如果用户是 editor 组的成员，他们将被授予 Editor 角色，否则为 Viewer。

   [auth.generic_oauth]
   enabled = true
   allow_sign_up = true
   auto_login = false
   team_ids =
   allowed_organizations =
   name = Auth0
   client_id = <client id>
   client_secret = <client secret>
   scopes = openid profile email offline_access
   auth_url = https://<domain>/authorize
   token_url = https://<domain>/oauth/token
   api_url = https://<domain>/userinfo
   use_pkce = true
   use_refresh_token = true

使用 Bitbucket 设置 OAuth2

要使用 Bitbucket 设置通用 OAuth 身份验证，请按照以下步骤操作

1. 导航到 BitBucket 中的 设置 > 工作区设置 > OAuth 使用者。

2. 通过选择 添加使用者 并使用以下参数来创建应用程序

   • 允许的回调 URL：https://<grafana domain>/login/generic_oauth

3. 单击 保存。

4. 使用使用者描述中的 Key 和 Secret 中的值更新 Grafana 配置文件的 [auth.generic_oauth] 部分

   在以下更复杂的示例中，用户已被授予 Admin 角色。这是因为他们是其 OAuth2 提供程序的 admin 组的成员。如果用户是 editor 组的成员，他们将被授予 Editor 角色，否则为 Viewer。

   [auth.generic_oauth]
   name = BitBucket
   enabled = true
   allow_sign_up = true
   auto_login = false
   client_id = <client key>
   client_secret = <client secret>
   scopes = account email
   auth_url = https://bitbucket.org/site/oauth2/authorize
   token_url = https://bitbucket.org/site/oauth2/access_token
   api_url = https://api.bitbucket.org/2.0/user
   teams_url = https://api.bitbucket.org/2.0/user/permissions/workspaces
   team_ids_attribute_path = values[*].workspace.slug
   team_ids =
   allowed_organizations =
   use_refresh_token = true

默认情况下，刷新令牌包含在 授权码授予 的响应中。

使用 OneLogin 设置 OAuth2

要使用 OneLogin 设置通用 OAuth 身份验证，请按照以下步骤操作

1. 在 OneLogin 中使用以下设置创建一个新的自定义连接器

   • 名称：Grafana
   • 登录方式：OpenID Connect
   • 重定向 URI：https://<grafana domain>/login/generic_oauth
   • 签名算法：RS256
   • 登录 URL：https://<grafana domain>/login/generic_oauth

2. 向 Grafana 连接器添加应用

   • 显示名称：Grafana

3. 使用应用详细信息页面的 SSO 选项卡中的客户端 ID 和客户端密钥更新 Grafana 配置文件的 [auth.generic_oauth] 部分

   您的 OneLogin 域将与您用于访问 OneLogin 的 URL 匹配。

   在以下更复杂的示例中，用户已被授予 Admin 角色。这是因为他们是其 OAuth2 提供程序的 admin 组的成员。如果用户是 editor 组的成员，他们将被授予 Editor 角色，否则为 Viewer。

   [auth.generic_oauth]
   name = OneLogin
   enabled = true
   allow_sign_up = true
   auto_login = false
   client_id = <client id>
   client_secret = <client secret>
   scopes = openid email name
   auth_url = https://<onelogin domain>.onelogin.com/oidc/2/auth
   token_url = https://<onelogin domain>.onelogin.com/oidc/2/token
   api_url = https://<onelogin domain>.onelogin.com/oidc/2/me
   team_ids =
   allowed_organizations =

使用 Dex 设置 OAuth2

要使用 Dex IdP 设置通用 OAuth 身份验证，请按照以下步骤操作

1. 在 Dex 配置 YAML 文件中将 Grafana 添加为客户端

   yaml 复制

   staticClients:
     - id: <client id>
       name: Grafana
       secret: <client secret>
       redirectURIs:
         - 'https://<grafana domain>/login/generic_oauth'

   注意

   与许多其他 OAuth2 提供商不同，Dex 不提供 <client secret>。相反，可以使用例如 openssl rand -hex 20 生成密钥。

2. 更新 Grafana 的 [auth.generic_oauth] 部分配置

   在以下更复杂的示例中，用户已被授予 Admin 角色。这是因为他们是其 OAuth2 提供程序的 admin 组的成员。如果用户是 editor 组的成员，他们将被授予 Editor 角色，否则为 Viewer。

   [auth.generic_oauth]
   name = Dex
   enabled = true
   client_id = <client id>
   client_secret = <client secret>
   scopes = openid email profile groups offline_access
   auth_url = https://<dex base uri>/auth
   token_url = https://<dex base uri>/token
   api_url = https://<dex base uri>/userinfo

   <dex base uri> 对应于 Dex 中的 issuer: 配置（例如，Dex 域，可能包含路径，例如 /dex）。当使用 刷新令牌 时，需要 offline_access 作用域。