使用 Azure CLI 将 Microsoft Entra ID 与 Azure Kubernetes 服务 (AKS) 集成（旧版）

项目
04/24/2024

警告

本文档中所述的功能 Microsoft Entra Integration（旧版）已于 2023 年 6 月 1 日弃用。目前，不能使用 Microsoft Entra Integration（旧版）创建新的群集。

AKS 提供经过改进的全新 AKS 托管 Microsoft Entra ID 体验，让你无需管理服务器或客户端应用程序。请遵照此处的说明进行迁移。

可将 Azure Kubernetes Service (AKS) 配置为使用 Microsoft Entra ID 进行用户身份验证。在此配置中，可以使用 Microsoft Entra 身份验证令牌登录到 AKS 群集。群集操作员还可以根据用户标识或目录组成员身份来配置 Kubernetes 基于角色的访问控制 (Kubernetes RBAC)。

本文介绍如何创建所需的 Microsoft Entra 组件，然后部署支持 Microsoft Entra ID 的群集，并在 AKS 群集中创建一个基本的 Kubernetes 角色。

限制

Microsoft Entra ID 只能在支持 Kubernetes RBAC 的群集上启用。
Microsoft Entra 传统集成只能在创建群集期间启用。

开始之前

需要安装并配置 Azure CLI 2.0.61 或更高版本。运行 az --version 即可查找版本。如果需要进行安装或升级，请参阅安装 Azure CLI。

为了保持一致并帮助运行本文中的命令，请为所需的 AKS 群集名称创建一个变量。以下示例使用名称 myakscluster：

aksname="myakscluster"

Microsoft Entra 身份验证概述

使用 OpenID Connect 向 AKS 群集提供 Microsoft Entra 身份验证。 OpenID Connect 是构建在 OAuth 2.0 协议顶层的标识层。有关 OpenID Connect 的详细信息，请参阅 OpenID Connect 文档。

在 Kubernetes 群集内部，使用 Webhook 令牌身份验证来验证身份验证令牌。 Webhook 令牌身份验证作为 AKS 群集的一部分进行配置和管理。有关 Webhook 令牌身份验证的详细信息，请参阅 Webhook 身份验证文档。

注意

为 AKS 身份验证配置 Microsoft Entra ID 时，将配置两个 Microsoft Entra 应用程序。此操作必须由 Azure 租户管理员完成。

创建 Microsoft Entra 服务器组件

若要与 AKS 集成，请创建并使用充当标识请求终结点的 Microsoft Entra 应用程序。需要的第一个 Microsoft Entra 应用程序获取用户的 Microsoft Entra 组成员身份。

使用 az ad app create 命令创建服务器应用程序组件，然后使用 az ad app update 命令更新组成员身份声明。以下示例使用开始之前部分中定义的 aksname 变量，并创建一个变量

# Create the Azure AD application
serverApplicationId=$(az ad app create \
    --display-name "${aksname}Server" \
    --identifier-uris "https://${aksname}Server" \
    --query appId -o tsv)

# Update the application group membership claims
az ad app update --id $serverApplicationId --set groupMembershipClaims=All

现在，使用 az ad sp create 命令创建服务器应用的服务主体。此服务主体用于在 Azure 平台中对自身进行身份验证。然后，使用 az ad sp credential reset 命令获取服务主体机密，并将其分配到名为 serverApplicationSecret 的变量，以便在以下步骤之一中使用：

# Create a service principal for the Azure AD application
az ad sp create --id $serverApplicationId

# Get the service principal secret
serverApplicationSecret=$(az ad sp credential reset \
    --name $serverApplicationId \
    --credential-description "AKSPassword" \
    --query password -o tsv)

Microsoft Entra 服务主体需要权限才能执行以下操作：

读取目录数据
登录并读取用户配置文件

使用 az ad app permission add 命令分配这些权限：

az ad app permission add \
    --id $serverApplicationId \
    --api 00000003-0000-0000-c000-000000000000 \
    --api-permissions e1fe6dd8-ba31-4d61-89e7-88639da4683d=Scope 06da0dbc-49e2-44d2-8312-53f166ab848a=Scope 7ab1d382-f21e-4acd-a863-ba3e13f7da61=Role

最后，使用 az ad app permission grant 命令授予在上一步骤中为服务器应用程序分配的权限。如果当前帐户不是租户管理员，此步骤将会失败。

az ad app permission grant --id $serverApplicationId --api 00000003-0000-0000-c000-000000000000
az ad app permission admin-consent --id  $serverApplicationId

创建 Microsoft Entra 客户端组件

当用户使用 Kubernetes CLI (kubectl) 登录到 AKS 群集时，将使用第二个 Microsoft Entra 应用程序。此客户端应用程序从用户接收身份验证请求，并验证其凭据和权限。使用 az ad app create 命令创建客户端组件的 Microsoft Entra 应用：

clientApplicationId=$(az ad app create \
    --display-name "${aksname}Client" \
    --native-app \
    --reply-urls "https://${aksname}Client" \
    --query appId -o tsv)

使用 az ad sp create 命令创建客户端应用程序的服务主体：

az ad sp create --id $clientApplicationId

使用 az ad app show 命令获取服务器应用的 oAuth2 ID，以允许两个应用组件之间的身份验证流。下一步骤将使用此 oAuth2 ID。

oAuthPermissionId=$(az ad app show --id $serverApplicationId --query "oauth2Permissions[0].id" -o tsv)

使用 az ad app permission add 命令添加对客户端应用程序和服务器应用程序组件的权限，以使用 oAuth2 通信流。然后，使用 az ad app permission grant 命令授予客户端应用程序与服务器应用程序通信的权限：

az ad app permission add --id $clientApplicationId --api $serverApplicationId --api-permissions ${oAuthPermissionId}=Scope
az ad app permission grant --id $clientApplicationId --api $serverApplicationId

部署群集

创建两个 Microsoft Entra 应用程序后，请创建 AKS 群集本身。首先使用 az group create 命令创建资源组。以下示例在 ChinaEast2 区域中创建资源组：

为群集创建资源组：

az group create --name myResourceGroup --location ChinaEast2

使用 az account show 命令获取 Azure 订阅的租户 ID。然后使用 az aks create 命令创建 AKS 群集。用于创建 AKS 群集的命令可提供服务器和客户端应用程序 ID、服务器应用程序服务主体机密和租户 ID：

tenantId=$(az account show --query tenantId -o tsv)

az aks create \
    --resource-group myResourceGroup \
    --name $aksname \
    --node-count 1 \
    --generate-ssh-keys \
    --aad-server-app-id $serverApplicationId \
    --aad-server-app-secret $serverApplicationSecret \
    --aad-client-app-id $clientApplicationId \
    --aad-tenant-id $tenantId

最后，使用 az aks get-credentials 命令获取群集管理员凭据。在以下步骤之一中，你将获得普通用户群集凭据，以查看 Microsoft Entra 身份验证流的运作方式。

az aks get-credentials --resource-group myResourceGroup --name $aksname --admin

创建 Kubernetes RBAC 绑定

在对 AKS 群集使用 Microsoft Entra 帐户之前，需要创建角色绑定或群集角色绑定。 “角色”定义要授予的权限，“绑定”将这些权限应用于目标用户。这些分配可应用于特定命名空间或整个群集。请参阅使用 Kubernetes RBAC 授权了解详细信息。

使用 az ad signed-in-user show 命令获取用户当前登录用户的用户主体名称 (UPN)。在下一步骤中，将为 Microsoft Entra 集成启用此用户帐户。

az ad signed-in-user show --query userPrincipalName -o tsv

重要

如果你为其授予 Kubernetes RBAC 绑定的用户在同一个 Microsoft Entra 租户中，请根据 userPrincipalName 分配权限。如果该用户位于不同的 Microsoft Entra 租户中，请查询并改用 objectId 属性。

创建名为 basic-azure-ad-binding.yaml 的 YAML 清单并粘贴以下内容。在最后一行中，请将 userPrincipalName_or_objectId 替换为前一命令的 UPN 或对象 ID 输出：

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: contoso-cluster-admins
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: userPrincipalName_or_objectId

使用 kubectl apply 命令创建群集角色绑定，并指定 YAML 清单的文件名：

kubectl apply -f basic-azure-ad-binding.yaml

使用 Microsoft Entra ID 访问群集

现在，让我们测试 AKS 群集的 Microsoft Entra 身份验证集成。将 kubectl 配置上下文设置为使用常规用户凭据。此上下文通过 Microsoft Entra ID 传回所有身份验证请求。

az aks get-credentials --resource-group myResourceGroup --name $aksname --overwrite-existing

现在，使用 kubectl get pods 命令查看所有命名空间中的 pod：

kubectl get pods --all-namespaces

你将收到一条登录提示，指出在 Web 浏览器中使用 Microsoft Entra 凭据进行身份验证。成功完成身份验证后，kubectl 命令会显示 AKS 群集中的 pod，如以下示例输出中所示：

kubectl get pods --all-namespaces

To sign in, use a web browser to open the page https://microsoft.com/deviceloginchina and enter the code BYMK7UXVD to authenticate.

NAMESPACE     NAME                                    READY   STATUS    RESTARTS   AGE
kube-system   coredns-754f947b4-2v75r                 1/1     Running   0          23h
kube-system   coredns-754f947b4-tghwh                 1/1     Running   0          23h
kube-system   coredns-autoscaler-6fcdb7d64-4wkvp      1/1     Running   0          23h
kube-system   heapster-5fb7488d97-t5wzk               2/2     Running   0          23h
kube-system   kube-proxy-2nd5m                        1/1     Running   0          23h
kube-system   kube-svc-redirect-swp9r                 2/2     Running   0          23h
kube-system   kubernetes-dashboard-847bb4ddc6-trt7m   1/1     Running   0          23h
kube-system   metrics-server-7b97f9cd9-btxzz          1/1     Running   0          23h
kube-system   tunnelfront-6ff887cffb-xkfmq            1/1     Running   0          23h

收到的 kubectl 身份验证令牌将会缓存。仅当令牌已过期或者重新创建了 Kubernetes 配置文件时，系统才会再次提示登录。

如果在使用 Web 浏览器成功登录后看到了以下示例输出中所示的授权错误消息，请检查以下问题：

error: You must be logged in to the server (Unauthorized)

你定义了适当的对象 ID 或 UPN，具体取决于用户帐户是否在同一 Microsoft Entra 租户中。
用户不是 200 多个组的成员。
服务器应用程序注册中定义的机密与使用 --aad-server-app-secret 配置的值相匹配
请确保在计算机上一次仅安装 kubectl 的一个版本。冲突的版本可能会导致在授权过程中出现问题。若要安装最新版本，请使用 az aks install-cli。

有关从 Microsoft Entra 集成迁移到 AKS 托管的 Microsoft Entra ID 的常见问题

1. 迁移计划是什么？

Microsoft Entra 集成（旧版）将于 2023 年 6 月 1 日弃用。在此日期之后，将无法使用 Microsoft Entra ID（旧版）创建新群集。从 2023 年 8 月 1 日起，我们将所有 Microsoft Entra 集成（旧版）AKS 群集迁移到 AKS 托管的 Microsoft Entra ID。我们每两周向受影响的订阅管理员发送一次通知电子邮件，提醒他们进行迁移。

2. 如果我不采取任何措施会怎么样？

Microsoft Entra Integration（旧版）AKS 群集将在 2023 年 6 月 1 日之后继续使用。从 2023 年 8 月 1 日起，我们会自动将群集迁移到 AKS 托管的 Microsoft Entra ID。在迁移期间，你可能会遇到 API 服务器停机的情况。

迁移后，kubeconfig 内容会发生更改。你需要使用 az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> 将新凭据合并到 kubeconfig 文件中。

建议在 8 月 1 日之前手动将 AKS 群集更新为 AKS 托管的 Microsoft Entra ID。这样，你就能够在更加便利的非工作时间管理停机情况。

3. 为什么手动迁移后仍然收到通知电子邮件？

电子邮件发送需要几天时间。如果在我们发起电子邮件发送过程之前未迁移群集，那么你仍然可能会收到通知。

4.如何检查群集是否已迁移到 AKS 托管的 Microsoft Entra ID？

使用 az aks show 命令确认 AKS 群集已迁移到 AKS 托管的 Microsoft Entra ID。

az aks show -g <RGName> -n <ClusterName>  --query "aadProfile"

如果群集使用的是 AKS 托管的 Microsoft Entra ID，则输出显示 managed 为 true。例如：

    {
      "adminGroupObjectIDs": [
        "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      ],
      "adminUsers": null,
      "clientAppId": null,
      "enableAzureRbac": null,
      "managed": true,
      "serverAppId": null,
      "serverAppSecret": null,
      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }

后续步骤

有关包含本文中所示命令的完整脚本，请参阅 [AKS 示例存储库中的 Microsoft Entra 集成脚本][完整脚本]。

请参阅在 AKS 中使用 Kubernetes 基于角色的访问控制和 Microsoft Entra 标识来控制对群集资源的访问，了解如何使用 Microsoft Entra 用户和组来控制对群集资源的访问。

有关如何保护 Kubernetes 群集的详细信息，请参阅 AKS 的访问和标识选项。

有关标识和资源控制的最佳做法，请参阅有关 AKS 中的身份验证和授权的最佳做法。

通过