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

配置通用 OAuth2 身份验证

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

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

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

• Azure AD OAuth
• GitHub OAuth
• GitLab OAuth
• Google OAuth
• 使用 OAuth 的 Grafana
• Keycloak OAuth
• Okta OAuth

如果你的 OAuth2 提供商不在列表中，你可以使用通用的 OAuth2 身份验证。

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

开始之前

要遵循本指南

• 确保你知道如何在你的 OAuth2 提供商中创建 OAuth2 应用程序。请参考你的 OAuth2 提供商的文档以获取更多信息。
• 确保你的身份提供者返回与 OpenID UserInfo 兼容的信息，例如 sub 声明。
• 如果你正在使用刷新令牌，确保你知道如何在你的 OAuth2 提供商中设置它们。请参考你的 OAuth2 提供商的文档以获取更多信息。

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

作为 Grafana 管理员，您可以使用通用 OAuth UI 在 Grafana 内部配置通用 OAuth2 客户端。为此，导航到 管理 > 身份验证 > 通用 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
  }
}

请参阅Terraform 注册表以了解使用 grafana_sso_settings 资源的全套参考。

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

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

步骤

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

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

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

   确保回调 URL 是完整的 HTTP 地址，你可以通过浏览器访问 Grafana，但需要附加路径 /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	启用通用OAuth2身份验证。将此值设置为true。

   查看其他通用OAuth2配置选项列表，并根据需要完成它们。

4. 可选：配置刷新令牌

   a. 将Grafana配置文件中[auth.generic_oauth]部分的scopes字段扩展为您的OAuth2提供商使用的刷新令牌作用域。

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

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

5. 配置角色映射.

6. 可选：配置团队同步。

7. 重新启动Grafana。

   现在您应该在登录页面上看到通用OAuth2登录按钮，并能够使用OAuth2提供商登录或注册。

配置登录

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

请参考以下表格，根据您的Oauth2提供商返回的用户登录方式确定配置信息

配置显示名称

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

请参考以下表格，根据您的Oauth2提供商返回的用户名称方式确定配置信息

配置电子邮件地址

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

根据OAuth2提供者返回的用户电子邮件地址，请参考以下表格了解需要配置的内容

配置刷新令牌

在Grafana v9.3及以后版本中可用。

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

Grafana使用刷新令牌来获取新的访问令牌，而无需用户再次登录。如果没有刷新令牌，当访问令牌过期后，Grafana会从系统中注销用户。

要配置通用的OAuth2以使用刷新令牌，将use_refresh_token配置选项设置为true，并根据需要执行以下一个或两个步骤：

1. 将scopes字段扩展到Grafana配置文件中[auth.generic_oauth]部分的额外范围。
2. 在提供者上启用刷新令牌。

注意：在Grafana v10.3.0中已删除accessTokenExpirationCheck功能开关，将使用use_refresh_token配置值来配置刷新令牌获取和访问令牌过期检查。

配置角色映射

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

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

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

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

要简化适当的JMESPath表达式的配置，请访问JMESPath以测试和评估具有自定义负载的表达式。

角色映射示例

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

映射用户组织角色

在这个示例中，用户已被授予编辑器角色。分配的角色基于属性role的值，该值必须是一个有效的Grafana角色，例如管理员、编辑器、查看者或无。

有效载荷

json 复制

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

配置

bash 复制

role_attribute_path = role

在以下更复杂的示例中，用户被授予了管理员角色。这是因为他们是OAuth2提供者中admin组的成员。如果用户是editor组的成员，他们将获得编辑器角色，否则为查看者。

有效载荷

json 复制

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

配置

bash 复制

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

映射服务器管理员角色

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

有效载荷

json 复制

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

配置

ini 复制

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

将一个角色映射给所有用户

在这个示例中，所有用户都会被分配查看者角色，无论从身份提供者接收到的用户信息如何。

配置

ini 复制

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

组织角色映射示例

在这个示例中，用户在org_foo组织中获得了查看者角色，在org_bar和org_baz组织中获得了编辑器角色。

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

有效载荷

json 复制

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

配置

ini 复制

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

配置团队同步

注意：此功能在Grafana Enterprise和Grafana Cloud中可用。

通过使用团队同步，您可以将您的OAuth2组链接到Grafana中的团队。这将自动将用户分配到相应的团队。当用户登录时，同步每个用户的团队。

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

要了解更多关于团队同步的信息，请参阅配置团队同步。

团队同步示例

配置

bash 复制

groups_attribute_path = info.groups

有效载荷

json 复制

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

配置选项

以下表格概述了各种通用OAuth2配置选项。您可以将这些选项作为环境变量应用，类似于Grafana中的任何其他配置。

设置通用 OAuth2 的示例

本节包括设置通用 OAuth2 集成的示例。

使用 Descope 设置 OAuth2

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

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

2. 如果您想使用除“注册或登录”之外的流程，请转到控制台中的IdP应用程序菜单，并选择您的IdP应用程序。然后修改流程托管URL查询参数?flow=sign-up-or-in以更改您想要使用的流程ID。

3. 点击保存。

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

   注意

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

   bash 复制

   [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的通用OAuth2身份验证，请按照以下步骤操作

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

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

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

3. 点击保存更改。

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

   bash 复制

   [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的通用OAuth2身份验证，请按照以下步骤操作

1. 在BitBucket中导航到设置 > 工作空间设置 > OAuth消费者。

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

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

3. 点击保存。

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

   bash 复制

   [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的通用OAuth2身份验证，请按照以下步骤操作

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

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

2. 将应用程序添加到Grafana连接器

   • 显示名称：Grafana

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

   您的OneLogin域将与您访问OneLogin时使用的URL相匹配。

   bash 复制

   [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的通用OAuth2身份验证，请按照以下步骤操作

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]部分

   bash 复制

   [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范围。