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

配置通用OAuth2身份验证

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

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

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

• Azure AD OAuth
• GitHub OAuth
• GitLab OAuth
• Google OAuth
• Grafana Com OAuth
• 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 Copy

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配置文件。

步骤

要使用我们的通用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	Your OAuth2提供商的授权端点。
   api_url	Your OAuth2提供商的用户信息端点。此端点返回的信息必须与OpenID UserInfo兼容。
   enabled	启用通用OAuth2身份验证。将此值设置为true。

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

4. 可选：配置刷新令牌

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

   b. 将[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. 通过附加额外的作用域到Grafana配置文件的[auth.generic_oauth]部分的scopes字段来扩展。
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_mapping》）和常规角色映射（《role_attribute_path》），则用户将获得两种映射角色中的最高角色。

为简化合适的JMESPath表达式的配置，请访问JMESPath以使用自定义有效载荷测试和评估表达式。

角色映射示例

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

映射用户组织角色

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

有效载荷

json Copy

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

配置

bash Copy

role_attribute_path = role

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

有效载荷

json Copy

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

配置

bash Copy

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

映射服务器管理员角色

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

有效载荷

json Copy

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

配置

ini Copy

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

映射一个角色给所有用户

在这个例子中，所有用户都会被分配Viewer角色，无论接收到的用户信息来自何种身份提供者。

配置

ini Copy

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

组织角色的映射示例

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

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

有效载荷

json Copy

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

配置

ini Copy

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企业版和Grafana云服务。

使用团队同步，您可以将OAuth2组链接到Grafana内部的团队。这将自动将用户分配到适当的团队。用户登录时，将同步每个用户的团队。

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

有关团队同步的更多信息，请参阅配置团队同步。

团队同步示例

配置

bash Copy

groups_attribute_path = info.groups

有效载荷

json Copy

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

配置选项

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

通用OAuth2设置的示例

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

使用Descope设置OAuth2

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

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

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

3. 点击保存。

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

   注意

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

   bash Copy

   [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 domain>/login/generic_oauth。

3. 点击保存更改。

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

   bash Copy

   [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

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

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

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

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

3. 点击保存。

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

   bash Copy

   [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

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

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。

   bash Copy

   [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. 将Grafana添加到Dex配置YAML文件中的客户端

   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 Copy

   [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作用域。