文档 Grafana 文档 设置 配置安全性 配置认证 GitLab OAuth

配置 GitLab OAuth 认证

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

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

本文档介绍如何配置 GitLab OAuth 认证。

开始之前

确保您知道如何创建 GitLab OAuth 应用。有关更多信息，请查阅 GitLab 关于创建 GitLab OAuth 应用的文档。

创建 GitLab OAuth 应用

1. 登录您的 GitLab 账户，然后转到个人资料 > 偏好设置 > 应用。
2. 点击添加新应用。
3. 填写字段。
   • 在重定向 URI 字段中，输入以下内容：https://<YOUR-GRAFANA-URL>/login/gitlab，并在范围列表中勾选 openid、email、profile。
   • 保持机密复选框选中状态。
4. 点击保存应用。
5. 记下您的应用 ID（这是 Client Id）和密钥（这是 Client Secret）。

使用 Grafana UI 配置 GitLab 认证客户端

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

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

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

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

使用 Terraform Provider 配置 GitLab 认证客户端

terraform 复制

resource "grafana_sso_settings" "gitlab_sso_settings" {
  provider_name = "gitlab"
  oauth2_settings {
    name                  = "Gitlab"
    client_id             = "YOUR_GITLAB_APPLICATION_ID"
    client_secret         = "YOUR_GITLAB_APPLICATION_SECRET"
    allow_sign_up         = true
    auto_login            = false
    scopes                = "openid email profile"
    allowed_domains       = "mycompany.com mycompany.org"
    role_attribute_path   = "contains(groups[*], 'example-group') && 'Editor' || 'Viewer'"
    role_attribute_strict = false
    allowed_groups        = "[\"admins\", \"software engineers\", \"developers/frontend\"]"
    use_pkce              = true
    use_refresh_token     = true
  }
}

有关使用 grafana_sso_settings 资源的完整参考，请访问 Terraform Registry。

使用 Grafana 配置文件配置 GitLab 认证客户端

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

步骤

要配置 Grafana 的 GitLab 认证，请按照以下步骤操作

1. 在 GitLab 中创建 OAuth 应用。

   1. 将重定向 URI 设置为 http://<my_grafana_server_name_or_ip>:<grafana_server_port>/login/gitlab。

      确保重定向 URI 是您通过浏览器访问 Grafana 的完整 HTTP 地址，并附加路径 /login/gitlab。

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

   2. 将 OAuth2 范围设置为 openid、email 和 profile。

2. 请参考下表更新 Grafana 配置文件中 [auth.gitlab] 部分的字段值

   字段	描述
   client_id, client_secret	这些值必须与您的 GitLab OAuth 应用的 Application ID 和 Secret 相匹配。
   enabled	启用 GitLab 认证。将此值设置为 true。

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

3. 可选：配置刷新令牌

   a. 在 Grafana 配置文件中 [auth.gitlab] 部分将 use_refresh_token 设置为 true。

4. 配置角色映射.

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

6. 重启 Grafana。

   您现在应该在登录页面看到一个 GitLab 登录按钮，并且可以使用您的 GitLab 账户登录或注册。

配置刷新令牌

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

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

默认情况下，GitLab 提供刷新令牌。

自 Grafana v10.1.0 起，GitLab 提供商默认启用刷新令牌获取和访问令牌过期检查。如果您想禁用访问令牌过期检查，则将 use_refresh_token 配置值设置为 false。

配置允许的群组

要限制仅允许属于一个或多个 GitLab 群组成员的认证用户访问，请将 allowed_groups 设置为以逗号或空格分隔的群组列表。

GitLab 的群组通过群组名称引用。例如，developers。要引用子群组 frontend，请使用 developers/frontend。请注意，在 GitLab 中，群组或子群组名称并不总是与其显示名称匹配，特别是当显示名称包含空格或特殊字符时。请务必始终使用群组或子群组 URL 中显示的名称。

配置角色映射

除非启用 skip_org_role_sync 选项，否则用户的角色将在用户登录时设置为从 GitLab 检索到的角色。

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

您可以使用 org_mapping 配置选项将用户分配到多个组织，并根据其 GitLab 群组成员资格指定其角色。有关更多信息，请参阅组织角色映射示例。如果指定了组织角色映射（org_mapping）并且 Entra ID 返回有效的角色，则用户将获得两者中最高的角色。

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

为了简化正确 JMESPath 表达式的配置，请访问 JMESPath 使用自定义负载测试和评估表达式。

角色映射示例

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

组织角色映射示例

GitLab 集成使用 org_mapping 配置中的外部用户组根据其 GitLab 群组成员资格映射组织和角色。

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

外部用户是以下 GitLab 群组的成员：groupd-1 和 group-2。

配置

ini 复制

org_mapping = group-1:org_foo:Viewer groupd-1:org_bar:Editor *:org_baz:Editor

使用 OAuth 令牌中的用户信息映射角色

在此示例中，电子邮件为 admin@company.com 的用户被授予 Admin 角色。所有其他用户被授予 Viewer 角色。

ini 复制

role_attribute_path = email=='admin@company.com' && 'Admin' || 'Viewer'

使用群组映射角色

在此示例中，来自 GitLab 群组“example-group”的用户被授予 Editor 角色。所有其他用户被授予 Viewer 角色。

ini 复制

role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'

映射服务器管理员角色

在此示例中，电子邮件为 admin@company.com 的用户被授予 Admin 组织角色以及 Grafana 服务器管理员角色。所有其他用户被授予 Viewer 角色。

bash 复制

role_attribute_path = email=='admin@company.com' && 'GrafanaAdmin' || 'Viewer'

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

在此示例中，无论从身份提供商接收到何种用户信息，所有用户都将被分配 Viewer 角色。

ini 复制

role_attribute_path = "'Viewer'"
skip_org_role_sync = false

Grafana 中的 GitLab 配置示例

本节包含 Grafana 配置文件中 GitLab 配置的示例。

bash 复制

[auth.gitlab]
enabled = true
allow_sign_up = true
auto_login = false
client_id = YOUR_GITLAB_APPLICATION_ID
client_secret = YOUR_GITLAB_APPLICATION_SECRET
scopes = openid email profile
auth_url = https://gitlab.com/oauth/authorize
token_url = https://gitlab.com/oauth/token
api_url = https://gitlab.com/api/v4
role_attribute_path = contains(groups[*], 'example-group') && 'Editor' || 'Viewer'
role_attribute_strict = false
allow_assign_grafana_admin = false
allowed_groups = ["admins", "software engineers", "developers/frontend"]
allowed_domains = mycompany.com mycompany.org
tls_skip_verify_insecure = false
use_pkce = true
use_refresh_token = true

配置团队同步

通过使用团队同步，您可以将 GitLab 群组映射到 Grafana 中的团队。这将自动将用户分配到适当的团队。每个用户的团队会在用户登录时进行同步。

GitLab 群组通过群组名称引用。例如，developers。要引用子群组 frontend，请使用 developers/frontend。请注意，在 GitLab 中，群组或子群组名称并不总是与其显示名称匹配，特别是当显示名称包含空格或特殊字符时。请务必始终使用群组或子群组 URL 中显示的名称。

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

配置选项

下表描述了所有 GitLab OAuth 配置选项。您可以将这些选项作为环境变量应用，与其他 Grafana 配置类似。有关更多信息，请参阅使用环境变量覆盖配置。