使用 Azure CLI 整合 Microsoft Entra ID 與 Azure Kubernetes Service (AKS) (舊版)

發行項
03/12/2024

警告

本文件所述的 Microsoft Entra 整合 (舊版) 功能已於 2023 年 6 月 1 日淘汰。目前，無法使用 Microsoft Entra 整合建立任何新叢集 (舊版)。

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 角色。

限制

只有已啟用 Kubernetes RBAC 的叢集才能啟用 Microsoft Entra ID。
只有在叢集建立期間才能啟用 Microsoft Entra 舊版整合。

開始之前

您必須安裝並設定 Azure CLI 版本 2.0.61 或更新版本。執行 az --version 以尋找版本。如果您需要安裝或升級，請參閱安裝 Azure CLI。

移至 https://shell.azure.com，並在您的瀏覽器中開啟 Cloud Shell。

基於一致性及有助於執行本文中的命令，請為所需的 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 admin-consent 來新增權限，讓 Microsoft Entra 應用程式要求資訊，否則可能需要系統管理同意：

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 識別碼，以允許兩個應用程式元件之間的驗證流程。下一個步驟會使用此 oAuth2 識別碼。

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 命令建立資源群組。下列範例在 EastUS 區域中建立資源群組：

建立叢集的資源群組：

az group create --name myResourceGroup --location EastUS

使用 az account show 命令取得 Azure 訂用帳戶的租用戶識別碼。然後，使用 az aks create 命令建立 AKS 叢集。建立 AKS 叢集的命令會提供伺服器和用戶端應用程式識別碼、伺服器應用程式服務主體密碼，以及您的租用戶識別碼：

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 繫結

必須先建立角色繫結或叢集角色繫結，Microsoft Entra 帳戶才能搭配 AKS 叢集使用。「角色」會定義要授與的權限，而「繫結」會將角色套用至需要的使用者。這些指派可以套用至指定的命名空間或在整個叢集中套用。如需詳細資訊，請參閱使用 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 的檔案，並將下列內容貼上。在最後一行，將 userPrincipalName_or_objectId 換成上一個命令的 UPN 或物件識別碼輸出：

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 命令建立 ClusterRoleBinding，並指定 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

您會收到登入提示，要求在網頁瀏覽器中使用 Microsoft Entra 認證進行驗證。成功驗證之後，kubectl 命令會顯示 AKS 叢集上的 Pod，如下列範例輸出所示：

kubectl get pods --all-namespaces

To sign in, use a web browser to open the page https://microsoft.com/devicelogin 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 組態檔時，才會重新提示您登入。

使用網頁瀏覽器成功登入之後，如果您看到授權錯誤訊息，如下列範例輸出所示，請檢查下列可能的問題：

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

您根據使用者帳戶是否在相同的 Microsoft Entra 租用戶中，定義適當的物件識別碼或 UPN。
使用者不是 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 整合 (舊版) 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 整合指令碼][complete-script]。

若要使用 Microsoft Entra 使用者和群組來控制存取叢集資源，請參閱使用 Kubernetes 角色型存取控制和 AKS 中的 Microsoft Entra 身分識別來控制存取叢集資源。

如需如何保護 Kubernetes 叢集的詳細資訊，請參閱 AKS 的存取和身分識別選項。

如需身分識別和資源控制的最佳做法，請參閱 AKS 中驗證和授權的最佳做法。