文档 Grafana 文档 设置 配置安全 配置认证 Azure AD/Entra ID OAuth

配置 Azure AD/Entra ID OAuth 认证

Azure AD 认证允许你使用 Microsoft Entra ID（以前称为 Azure Active Directory）租户作为 Grafana 的身份提供商。你可以从 Azure Portal 使用 Entra ID 应用程序角色将用户和组分配给 Grafana 角色。

创建 Microsoft Entra ID 应用程序

要启用 Azure AD/Entra ID OAuth，请在 Entra ID 中注册你的应用程序。

1. 登录到Azure Portal，然后在侧边菜单中点击 Microsoft Entra ID。

2. 如果你有多个租户的访问权限，请在右上角选择你的帐户。将你的会话设置为你想使用的 Entra ID 租户。

3. 在侧边菜单的管理下，点击应用注册 > 新建注册。输入一个描述性的名称。

4. 在重定向 URI下，选择应用类型Web。

5. 添加重定向 URL https://<grafana domain>/login/azuread 和 https://<grafana domain>，然后点击注册。应用程序的概览页面将打开。

6. 记下应用程序 ID。这就是 OAuth 客户端 ID。

7. 从顶部菜单点击终结点。

   • 记下OAuth 2.0 授权终结点 (v2) URL。这就是授权 URL。
   • 记下OAuth 2.0 令牌终结点 (v2)。这就是令牌 URL。

8. 在侧边菜单中点击证书和密钥，然后在你想要使用的支持的客户端认证选项下添加一个新条目。以下是支持的客户端认证选项及其相应的配置步骤。

   • 客户端密钥

     1. 在客户端密钥下添加一个新条目，配置如下。

        • 描述：Grafana OAuth 2.0
        • 过期时间：选择一个过期周期

     2. 点击添加，然后复制密钥的值。这就是 OAuth 2.0 客户端密钥。

     注意

     确保复制的是值字段中的字符串，而不是密钥 ID字段中的。

     1. 要使此功能生效，必须在 Grafana 服务器配置的 [auth.azuread] 部分将 client_authentication 设置为 client_secret_post。

   • 联合身份凭据

     1. 有关将托管身份设置为联合身份凭据的完整指南，请参阅配置应用程序以信任托管身份（预览）。在联合身份凭据下添加一个新条目，配置如下。

        • 联合身份凭据场景：选择其他颁发者。
        • 颁发者：Microsoft Entra ID 机构的 OAuth 2.0 / OIDC 颁发者 URL。例如：https://login.microsoftonline.com/{tenantID}/v2.0。
        • 主体标识符：托管身份的对象（Principal）ID GUID。
        • 名称：凭据的唯一描述性名称。
        • 描述：Grafana OAuth。
        • 受众：必须出现在外部令牌中的受众值。对于公共云，它将是 api://AzureADTokenExchange。有关可用受众的完整列表，请参阅相关文档。

     2. 点击添加，然后复制托管身份客户端 ID 和联合身份凭据的受众值。这就是你的 OAuth 2.0 联合身份凭据。

     3. 要使此功能生效，必须在 Grafana 服务器配置的 [auth.azuread] 部分将 client_authentication 设置为 managed_identity。

     注意

     作为联合身份凭据的托管身份仅适用于托管在 Azure 中的工作负载。

     你只能将用户分配的托管身份添加为 Entra ID 应用程序上的联合身份凭据。

9. 使用Azure Portal或清单文件为 Grafana 定义所需的应用程序角色。

10. 转到 Microsoft Entra ID，然后在管理下转到企业应用程序。

11. 搜索你的应用程序并点击它。

12. 点击用户和组。

13. 点击添加用户/组将用户或组添加到 Grafana 角色。

在 Azure Portal 中为 Grafana 配置应用程序角色

本节描述如何在 Azure Portal 中为 Grafana 设置基本的应用程序角色。有关更多信息，请参阅将应用程序角色添加到应用程序并在令牌中接收它们。

1. 转到应用注册，搜索你的应用程序并点击它。

2. 点击应用角色，然后点击创建应用角色。

3. 为每个 Grafana 角色定义一个相应的角色：Viewer、Editor 和 Admin。

   1. 为角色选择一个显示名称。例如，“Grafana 编辑器”。

   2. 将允许的成员类型设置为用户/组。

   3. 确保值字段与 Grafana 角色名称匹配。例如，“Editor”。

   4. 为角色选择一个描述。例如，“Grafana 编辑器用户”。

   5. 点击应用。

在清单文件中为 Grafana 配置应用程序角色

如果你更喜欢在清单文件中为 Grafana 配置应用程序角色，请完成以下步骤

1. 转到应用注册，搜索你的应用程序并点击它。

2. 点击清单。

3. 为每个角色添加一个全局唯一标识符。

1. 将清单文件中的每个“SOME_UNIQUE_ID”替换为生成的 ID

   json 复制

   	"appRoles": [
   			{
   				"allowedMemberTypes": [
   					"User"
   				],
   				"description": "Grafana org admin Users",
   				"displayName": "Grafana Org Admin",
   				"id": "SOME_UNIQUE_ID",
   				"isEnabled": true,
   				"lang": null,
   				"origin": "Application",
   				"value": "Admin"
   			},
   			{
   				"allowedMemberTypes": [
   					"User"
   				],
   				"description": "Grafana read only Users",
   				"displayName": "Grafana Viewer",
   				"id": "SOME_UNIQUE_ID",
   				"isEnabled": true,
   				"lang": null,
   				"origin": "Application",
   				"value": "Viewer"
   			},
   			{
   				"allowedMemberTypes": [
   					"User"
   				],
   				"description": "Grafana Editor Users",
   				"displayName": "Grafana Editor",
   				"id": "SOME_UNIQUE_ID",
   				"isEnabled": true,
   				"lang": null,
   				"origin": "Application",
   				"value": "Editor"
   			}
   		],

2. 点击保存。

分配服务器管理员权限

如果 Grafana 收到的应用程序角色是 GrafanaAdmin，Grafana 将授予用户服务器管理员权限。如果你想将服务器管理员权限授予部分用户，这会很有用。Grafana 还会将用户分配到默认组织的 Admin 角色。

要使此功能生效，[auth.azuread] 下的设置 allow_assign_grafana_admin 必须设置为 true。如果此设置设置为 false，则用户将被分配默认组织的 Admin 角色，但没有服务器管理员权限。

json 复制

{
  "allowedMemberTypes": ["User"],
  "description": "Grafana server admin Users",
  "displayName": "Grafana Server Admin",
  "id": "SOME_UNIQUE_ID",
  "isEnabled": true,
  "lang": null,
  "origin": "Application",
  "value": "GrafanaAdmin"
}

开始之前

开始之前，请确保你已按照创建 Microsoft Entra ID 应用程序中的步骤操作。

使用 Grafana UI 配置 Azure AD 认证客户端

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

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

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

使用 Terraform provider 配置 Azure AD 认证客户端

terraform 复制

resource "grafana_sso_settings" "azuread_sso_settings" {
  provider_name = "azuread"
  oauth2_settings {
    name                          = "Azure AD"
    auth_url                      = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize"
    token_url                     = "https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token"
    client_authentication         = "CLIENT_AUTHENTICATION_OPTION"
    client_id                     = "APPLICATION_ID"
    client_secret                 = "CLIENT_SECRET"
    managed_identity_client_id    = "MANAGED_IDENTITY_CLIENT_ID"
    federated_credential_audience = "FEDERATED_CREDENTIAL_AUDIENCE"
    allow_sign_up                 = true
    auto_login                    = false
    scopes                        = "openid email profile"
    allowed_organizations         = "TENANT_ID"
    role_attribute_strict         = false
    allow_assign_grafana_admin    = false
    skip_org_role_sync            = false
    use_pkce                      = true
  }
}

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

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

确保你可以访问Grafana 配置文件。

在 Grafana 中启用 Azure AD OAuth

将以下内容添加到Grafana 配置文件中

复制

[auth.azuread]
name = Azure AD
enabled = true
allow_sign_up = true
auto_login = false
client_authentication = CLIENT_AUTHENTICATION_OPTION
client_id = APPLICATION_ID
client_secret = CLIENT_SECRET
managed_identity_client_id = MANAGED_IDENTITY_CLIENT_ID
federated_credential_audience = FEDERATED_CREDENTIAL_AUDIENCE
scopes = openid email profile
auth_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize
token_url = https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token
allowed_domains =
allowed_groups =
allowed_organizations = TENANT_ID
role_attribute_strict = false
allow_assign_grafana_admin = false
skip_org_role_sync = false
use_pkce = true

你也可以使用这些环境变量来配置 client_authentication、client_id、client_secret、managed_identity_client_id 和 federated_credential_audience。

复制

GF_AUTH_AZUREAD_CLIENT_AUTHENTICATION
GF_AUTH_AZUREAD_CLIENT_ID
GF_AUTH_AZUREAD_CLIENT_SECRET
GF_AUTH_AZUREAD_MANAGED_IDENTITY_CLIENT_ID
GF_AUTH_AZUREAD_FEDERATED_CREDENTIAL_AUDIENCE

配置刷新令牌

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

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

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

配置允许的租户

要限制只有属于一个或多个租户的认证用户才能访问，请将 allowed_organizations 设置为以逗号或空格分隔的租户 ID 列表。你可以在 Azure portal 的“Microsoft Entra ID”->“概览”下找到租户 ID。

如果你的 Entra ID 包含外部身份，请确保包含所有联合用户根目录的租户 ID。

例如，如果你只想允许 ID 为 8bab1c86-8fba-33e5-2089-1d1c80ec267d 的 example 租户成员访问，则设置以下内容

复制

allowed_organizations = 8bab1c86-8fba-33e5-2089-1d1c80ec267d

配置允许的组

配置允许的组

Microsoft Entra ID 组可用于限制用户对 Grafana 的访问。有关在 Entra ID 中管理组的更多信息，请参阅管理 Microsoft Entra 组和组员。

1. 要限制只有属于一个或多个 Entra ID 组的认证用户才能访问，请将 allowed_groups 设置为以逗号或空格分隔的组对象 ID 列表。

   要找到特定组的对象 ID，请在 Azure portal 上转到“Microsoft Entra ID”>“管理”>“组”。你也可以通过点击该组，然后点击“属性”来找到组的对象 ID。“对象 ID”下会列出对象 ID。如果你只想允许对象 ID 为 8bab1c86-8fba-33e5-2089-1d1c80ec267d 的 example 组成员访问，则设置以下内容

   复制

     allowed_groups = 8bab1c86-8fba-33e5-2089-1d1c80ec267d

2. 你必须在你的 Entra ID 应用注册中启用将组属性添加到令牌的功能，可以通过Azure Portal或通过清单文件进行配置。

在 Azure Portal 中配置组成员声明

为确保令牌中包含 groups 声明，请通过 Azure Portal UI 或编辑清单文件将 groups 声明添加到令牌配置中。

要从 Azure Portal UI 配置组成员声明，请完成以下步骤

1. 导航到应用注册页面并选择你的应用程序。
2. 在侧边菜单的管理下，选择令牌配置。
3. 点击添加组声明并选择适合你用例的相关选项（例如，安全组和分配给应用程序的组）。

有关更多信息，请参阅配置可选组声明。

在清单文件中配置组成员声明

1. 转到应用注册，搜索你的应用程序并点击它。

2. 点击清单。

3. 将以下内容添加到清单文件的根部

   复制

   "groupMembershipClaims": "ApplicationGroup, SecurityGroup"

配置允许的域

配置允许的域

复制

allowed_domains = mycompany.com mycompany.org

allowed_domains 选项限制只有属于特定域的用户才能访问。使用空格或逗号分隔域。例如，

PKCE

IETF 的RFC 7636引入了“代码交换的证明密钥”（PKCE），它提供了额外的保护，防止某些形式的授权码拦截攻击。PKCE 将在OAuth 2.1中成为必需项。

你可以通过在[auth.azuread]部分将 use_pkce 设置为 false 来禁用 Grafana 中的 PKCE。

配置自动登录

复制

auto_login = true

要绕过登录屏幕并自动登录，请启用“auto_login”功能。如果配置了多个认证提供商使用自动登录，此设置将被忽略。

Team Sync（仅限 Enterprise 版）

使用 Team Sync，你可以将你的 Entra ID 组映射到 Grafana 中的团队，以便你的用户自动添加到正确的团队。

你可以通过组对象 ID 引用 Entra ID 组，例如 8bab1c86-8fba-33e5-2089-1d1c80ec267d。

要了解更多信息，请参阅Team Sync文档。

常见故障排除

以下是在 Grafana 中配置 Azure AD 认证时可能遇到的一些常见问题和特殊情况。

成员超过 200 个组的用户

为确保令牌大小不超过 HTTP 头大小限制，Entra ID 限制了其在 groups 声明中包含的对象 ID 数量。如果用户的组数量超过覆盖限制 (200)，Entra ID 不会在令牌中发出 groups 声明，而是发出 group overage 声明。

更多信息请参阅组超额声明

如果 Grafana 收到带有 group overage 声明而不是 groups 声明的令牌，Grafana 会尝试通过调用包含的终结点来检索用户的组员信息。

否

配置所需的 Graph API 权限

1. 导航到Microsoft Entra ID > 管理 > 应用注册并选择你的应用程序。
2. 选择API 权限，然后点击添加权限。
3. 从 API 列表中选择Microsoft Graph。
4. 选择委派权限。
5. 在 GroupMember 部分下，选择 GroupMember.Read.All。
6. 点击添加权限。
7. 从 API 列表中选择Microsoft Graph。
8. 选择委派权限..。
9. 在选择权限窗格中，在 User 部分下，选择 User.Read。
10. 点击页面底部的添加权限按钮。

强制从 Microsoft Graph API 获取组

要强制从 Microsoft Graph API 获取组而不是从 id_token 获取，你可以使用 force_use_graph_api 配置选项。

复制

force_use_graph_api = true

映射角色

默认情况下，Azure AD 认证会根据在 Entra ID 中分配给用户权限最高的应用程序角色，将用户映射到组织角色。

如果找不到应用程序角色，则会将用户分配到由auto_assign_org_role 选项指定的角色。你可以通过设置 role_attribute_strict = true 来禁用此默认角色分配。如果未返回角色或返回的角色无效，并且 org_mapping 表达式评估为空映射，此设置将拒绝用户访问。

你可以使用 org_mapping 配置选项将用户分配到多个组织，并根据他们的 Entra ID 组员信息指定他们的角色。有关更多信息，请参阅组织角色映射示例。如果指定了组织角色映射 (org_mapping) 并且 Entra ID 返回了有效角色，则用户将获得两个角色中权限最高的一个。

每次登录时，用户组织角色将重置为与 Entra ID 的应用程序角色匹配，并且他们的组织员信息也将重置为默认组织。

组织角色映射示例

Entra ID 集成使用外部用户的组在 org_mapping 配置中，根据他们的 Entra ID 组员信息映射组织和角色。

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

外部用户属于以下 Entra ID 组：032cb8e0-240f-4347-9120-6f33013e817a 和 bce1c492-0679-4989-941b-8de5e6789cb9。

配置

ini 复制

org_mapping = ["032cb8e0-240f-4347-9120-6f33013e817a:org_foo:Viewer", "bce1c492-0679-4989-941b-8de5e6789cb9:org_bar:Editor", "*:org_baz:Editor"]

跳过组织角色同步

跳过组织角色同步

ini 复制

[auth.azuread]
# ..
# prevents the sync of org roles from AzureAD
skip_org_role_sync = true

配置选项

下表列出了各种 Azure AD/Entra ID 配置选项。你可以将这些选项作为环境变量应用，与 Grafana 中的任何其他配置类似。有关更多信息，请参阅使用环境变量覆盖配置。