你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为 Kubernetes 群集启用由 AKS 管理的 Microsoft Entra 集成，并使用 kubelogin

2025-10-08

AKS 管理的 Microsoft Entra 集成简化了 Microsoft Entra 集成过程。以前，你需要创建客户端和服务器应用，并且 Microsoft Entra 租户必须授予目录读取者角色权限。现在，Azure Kubernetes 服务（AKS）资源提供程序会为你管理客户端和服务器应用。

群集管理员可以根据用户的标识或目录组成员身份来配置 Kubernetes 基于角色的访问控制 (Kubernetes RBAC)。使用 OpenID Connect 向 AKS 群集提供 Microsoft Entra 身份验证。 OpenID Connect 是构建在 OAuth 2.0 协议顶层的标识层。有关 OpenID Connect 的详细信息，请参阅 OpenID Connect 文档。

在 Microsoft Entra 文档中了解有关 Microsoft Entra 集成流的详细信息。

限制

以下是在 AKS 上集成身份验证的约束：

添加后无法禁用集成。
不支持从集成群集降级到旧 Microsoft Entra ID 群集。
没有 Kubernetes RBAC 支持的群集无法添加到集成。

开始之前

若要安装 AKS 加载项，请验证是否具有以下项：

已安装并配置 Azure CLI 2.29.0 或更高版本。若要查找版本，请运行 az --version 命令。如果需要进行安装或升级，请参阅安装 Azure CLI。
你需要最低版本为 kubectl 或的 kubelogin。使用 Azure CLI 和 Azure PowerShell 模块时，这两个命令包含在内，并自动进行管理。这意味着，它们已默认升级，并且不需要或建议运行 az aks install-cli。如果使用的是自动化管道，则需要管理升级以达到正确或最新版本。 Kubernetes 和 kubectl 的次要版本之间的差异不应超过一个版本。否则，会在错误的版本上发生身份验证问题。
如果使用 helm，所需的最低版本为 helm 3.3。
此配置要求你为群集提供 Microsoft Entra 组。此组在群集上注册为管理员组，以授予管理员权限。如果没有现有的 Microsoft Entra 组，可以使用 az ad group create 命令创建一个。

注意

使用 1.24 版以上的 Kubernetes 版本的 Microsoft Entra 集成群集自动使用 kubelogin 格式。从 Kubernetes 版本 1.24 开始，Microsoft Entra ID 群集的凭据默认格式为clusterUser，此格式要求在执行PATH时使用kubelogin二进制文件。对于非 Microsoft Entra 群集或版本低于 1.24 的 Microsoft Entra ID 群集，不会有行为变化。已下载的现有 kubeconfig 将继续工作。在获取 clusterUser 凭据来覆盖默认行为更改时，包含一个可选的查询参数 format。如果需要维护旧azure格式，可以显式指定kubeconfig格式。

在 AKS 群集上启用集成

创建新群集

使用 az group create 命令创建 Azure 资源组。

az group create --name myResourceGroup --location centralus

创建一个 AKS 群集，并使用 az aks create 命令为 Microsoft Entra 组启用管理访问权限。

az aks create \
  --resource-group myResourceGroup \
  --name myManagedCluster \
  --enable-aad \
  --aad-admin-group-object-ids <id> \
  --aad-tenant-id <id> \
  --generate-ssh-keys

成功创建 AKS 托管的 Microsoft Entra ID 群集后，响应正文中会包含以下部分。

"AADProfile": {
  "adminGroupObjectIds": [
  "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
  ],
  "clientAppId": null,
  "managed": true,
  "serverAppId": null,
  "serverAppSecret": null,
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}

使用现有群集

使用 az aks update 命令在现有已启用 Kubernetes RBAC 的群集上启用 AKS 托管的 Microsoft Entra 集成。确保将管理员组设置为在群集上保留访问权限。

az aks update \
  --resource-group MyResourceGroup \
  --name myManagedCluster \
  --enable-aad \
  --aad-admin-group-object-ids <id-1>,<id-2> \
  --aad-tenant-id <id>

成功激活 AKS 托管的 Microsoft Entra ID 群集后，响应正文中会包含以下部分：

"AADProfile": {
  "adminGroupObjectIds": [
      "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
  ],
  "clientAppId": null,
  "managed": true,
  "serverAppId": null,
  "serverAppSecret": null,
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}

将旧群集迁移到集成

如果群集使用旧 Microsoft Entra 集成，可以通过 az aks update 命令升级到 AKS 管理的 Microsoft Entra 集成。

警告

升级期间，免费层群集可能会遇到 API 服务器停机的情况。建议在非工作时间进行升级。升级后， kubeconfig 内容会更改。需要运行 az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> 才能将新凭据合并到 kubeconfig 文件中。

az aks update \
  --resource-group myResourceGroup \
  --name myManagedCluster \
  --enable-aad \
  --aad-admin-group-object-ids <id> \
  --aad-tenant-id <id>

成功迁移 AKS 托管的 Microsoft Entra ID 群集后，响应正文中会包含以下部分：

"AADProfile": {
  "adminGroupObjectIds": [
      "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
  ],
  "clientAppId": null,
  "managed": true,
  "serverAppId": null,
  "serverAppSecret": null,
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}

访问已启用的群集

使用 az aks get-credentials 命令获取用户凭据以访问群集。

az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

请按照登录步骤进行。

将 kubelogin 设置为使用 Azure CLI。

kubelogin convert-kubeconfig -l azurecli

使用 kubectl get nodes 命令查看群集中的节点。
```
kubectl get nodes
```

有一些不支持 kubectl 的非交互式方案。在这些情况下，请使用 kubelogin 通过非交互式服务主体凭据连接到群集，以执行持续集成管道。

注意

使用 1.24 版以上的 Kubernetes 版本的 Microsoft Entra 集成群集自动使用 kubelogin 格式。从 Kubernetes 版本 1.24 开始，Microsoft Entra ID 群集的 clusterUser 凭据默认格式为 exec，这需要使用执行 PATH 中的 kubelogin 二进制文件。对于非 Microsoft Entra 群集或运行的版本低于 1.24 的 Microsoft Entra ID 群集，没有行为更改。已下载的现有 kubeconfig 将继续工作。在获取 clusterUser 凭据来覆盖默认行为更改时，包含一个可选的查询参数 format。如果需要维护旧azure格式，可以显式指定kubeconfig格式。

获取 clusterUser 凭据时，可以使用 format 查询参数覆盖默认行为。可以将值 azure 设置为使用原始 kubeconfig 格式：

az aks get-credentials --format azure

如果Microsoft Entra 集成群集使用 Kubernetes 版本 1.24 或更高版本，则需要手动转换 kubeconfig 格式。

export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

如果收到消息 错误消息：已删除 Azure 身份验证插件。需要运行该命令 kubelogin convert-kubeconfig 以手动转换 kubeconfig 格式。有关详细信息，请参阅 Azure Kubelogin 已知问题。

排查访问问题

重要说明

本部分中介绍的步骤推荐了一种替代常规 Microsoft Entra 组身份验证的身份验证方法。请仅在紧急情况下使用此选项。

如果缺少对有效 Microsoft Entra 组的管理访问权限，可以使用此解决方法。使用 Azure Kubernetes 服务群集管理员角色的成员帐户登录，并授予用来访问群集的组或租户管理员凭据。

后续步骤

了解 Microsoft Entra 与 Kubernetes RBAC 的集成。
详细了解 AKS 和 Kubernetes 标识概念。
了解如何对 AKS 中所有受支持的 Microsoft Entra 身份验证方法使用 kubelogin。
使用 Azure 资源管理器模板创建启用了 Microsoft Entra ID 的 AKS 管理集群。

反馈

此页面是否有帮助？