共用方式為

在 Azure Kubernetes Service 中使用 kubelogin 驗證使用者

  • 發行項

Azure 中的 kubelogin 外掛程式是實作 Microsoft Entra 驗證的 client-go 認證外掛程式 (英文)。 kubelogin 外掛程式提供 kubectl 命令列工具中無法使用的功能。 如需詳細資訊，請參閱 kubelogin 簡介 和 kubectl 簡介。

與 Microsoft Entra ID 整合且執行 Kubernetes 1.24 版或更新版本的 Azure Kubernetes Service (AKS) 叢集會自動使用 kubelogin 格式。

本文提供如何在 AKS 中針對所有支援的 Microsoft Entra 驗證方法使用 kubelogin 的概觀和範例。

限制

  • 您最多可在 Microsoft Entra JSON Web 權杖 (JWT) 宣告中包括 200 個群組。 如果您有 200 個以上的群組，請考慮使用應用程式角色 (部分機器翻譯)。
  • 在 Microsoft Entra ID 中建立的群組只會依其 ObjectID 值 (而非依其顯示名稱) 來加以包括。 sAMAccountName 命令僅適用於要從內部部署 Windows Server Active Directory 同步的群組。
  • 在 AKS 中，服務主體驗證方法只適用於受控的 Microsoft Entra ID，而不適用於舊版 Azure Active Directory。
  • 在 Microsoft Entra 租用戶上設定 Microsoft Entra 條件式存取原則時，裝置代碼驗證方法無法運作。 在該案例中，請使用網頁瀏覽器互動式驗證。

驗證的運作方式

針對大部分與 kubelogin 的互動，您可以使用 convert-kubeconfig 子命令。 子命令使用 --kubeconfig 中或 KUBECONFIG 環境變數中指定的 kubeconfig 檔案，根據指定的驗證方法，將最終 kubeconfig 檔案轉換成 exec 格式。

kubelogin 實作的驗證方法是 Microsoft Entra OAuth 2.0 權杖授與流程。 下列參數旗標常用於 kubelogin 子命令中。 通常，當您從 AKS 中取得 kubeconfig 檔案時，就能夠使用這些旗標。

  • --tenant-id：Microsoft Entra 租用戶識別碼。
  • --client-id：公用用戶端應用程式的應用程式識別碼。 此用戶端應用程式僅適用於裝置代碼、網頁瀏覽器互動式，以及 OAuth 2.0 資源擁有者密碼認證 (ROPC) (工作流程身分識別) 登入方法。
  • --server-id：Web 應用程式或資源伺服器的應用程式識別碼。 系統會將權杖發給此資源。

注意

在每個驗證方法中，不會將權杖快取於檔案系統上。

驗證方法

後續小節將描述支援的驗證方法，以及如何使用這些方法：

  • 裝置代碼
  • Azure CLI
  • 網頁瀏覽器互動式
  • 服務主體
  • 受控識別
  • 工作負載身分識別

裝置代碼

裝置代碼是適用於 convert-kubeconfig 子命令的預設驗證方法。 -l devicecode 是選用參數。 此驗證方法會提示使用者從瀏覽器工作階段登入的裝置代碼。

在引進 kubelogin 和 exec 外掛程式之前，kubectl 中的 Azure 驗證方法僅支援裝置代碼流程。 其使用舊版程式庫，該程式庫會產生具有前置詞為 spn: 之 audience 宣告的權杖。 其與使用代理者 (OBO) (部分機器翻譯) 流程的 AKS 受控 Microsoft Entra ID (部分機器翻譯) 不相容。 當您執行 convert-kubeconfig 子命令時，kubelogin 會從對象宣告中移除 spn: 前置詞。

如果您的需求包括使用舊版功能，請新增 --legacy 引數。 如果您在舊版 Azure Active Directory 叢集中使用 kubeconfig 檔案，kubelogin 會自動新增 --legacy 旗標。

在此登入方法中，存取權杖和重新整理權杖均會快取於 ${HOME}/.kube/cache/kubelogin 目錄中。 若要覆寫此路徑，請包括 --token-cache-dir 參數。

如果您的 AKS Microsoft Entra 整合式叢集使用 Kubernetes 1.24 或更早版本，就必須執行下列命令來手動轉換 kubeconfig 檔案格式：

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

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

若要清除快取的權杖，請執行下列命令：

kubelogin remove-tokens

注意

在 Microsoft Entra 租用戶上設定條件式存取原則時，裝置代碼登入方法無法運作。 在此案例中，請使用網頁瀏覽器互動式方法。

Azure CLI

Azure CLI 驗證方法會使用 Azure CLI 建立的登入內容來取得存取權杖。 系統會在與 az login 相同的 Microsoft Entra 租用戶中發出權杖。 kubelogin 不會將權杖寫入權杖快取檔案，因為其已經由 Azure CLI 管理。

注意

此驗證方法僅適用於 AKS 受控 Microsoft Entra ID。

下列範例示範如何使用 Azure CLI 方法進行驗證：

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

如果 Azure CLI 設定目錄位於 ${HOME} 目錄外部，請使用 --azure-config-dir 參數搭配 convert-kubeconfig 子命令。 此命令會產生已設定環境變數的 kubeconfig 檔案。 當您執行 kubectl 命令時，可以將 AZURE_CONFIG_DIR 環境變數設定為此目錄，以取得相同的設定。

網頁瀏覽器互動式

網頁瀏覽器互動式驗證方法會自動開啟網頁瀏覽器來將使用者登入。 當使用者通過驗證之後，瀏覽器就會使用已驗證的認證，重新導向本機 Web 伺服器。 此驗證方法符合條件式存取原則。

當您使用此方法進行驗證時，存取權杖就會快取於 ${HOME}/.kube/cache/kubelogin 目錄中。 您可以使用 --token-cache-dir 參數來覆寫此路徑。

持有人權杖

下列範例示範如何搭配網頁瀏覽器互動式流程使用持有人權杖：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

所有權證明權杖

下列範例示範如何搭配網頁瀏覽器互動式流程使用所有權證明 (PoP) 權杖：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

服務主體

此驗證方法使用服務主體來將使用者登入。 您可以透過設定環境變數或在命令列引數中使用認證來提供認證。 您可以使用的支援認證是密碼或個人資訊交換 (PFX) 用戶端憑證。

使用此方法之前，請考慮下列限制：

  • 此方法僅適用於受控的 Microsoft Entra ID。
  • 服務主體可以是最多 200 個 Microsoft Entra 群組 (部分機器翻譯) 的成員。

環境變數

下列範例示範如何使用環境變數來設定用戶端密碼：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<Service Principal Name (SPN) client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

然後執行此命令：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_SECRET=<SPN secret>

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

命令列引數

下列範例示範如何在命令列引數中設定用戶端密碼：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --client-id <SPN client ID> --client-secret <SPN client secret>

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

警告

命令列引數方法會將祕密儲存於 kubeconfig 檔案中。

用戶端憑證

下列範例示範如何使用用戶端憑證來設定用戶端密碼：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

然後執行此命令：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

PoP 權杖和環境變數

下列範例示範如何設定 PoP 權杖，以使用其從環境變數取得的用戶端密碼：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

受控識別

針對連線到支援 Microsoft Entra 驗證之資源的應用程式，請使用受控識別 (部分機器翻譯) 驗證方法。 範例包括存取 Azure 資源，例如，Azure 虛擬機器、虛擬機器擴展集或 Azure Cloud Shell。

預設受控識別

下列範例示範如何使用預設受控識別：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

特定身分識別

下列範例示範如何搭配特定身分識別使用預設受控識別：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

工作負載身分識別

工作負載身分識別驗證方法使用與 Microsoft Entra 同盟的身分識別認證來驗證對 AKS 叢集的存取。 此方法使用 Microsoft Entra 整合式驗證。 其透過設定下列環境變數來運作：

  • AZURE_CLIENT_ID：與工作負載身分識別同盟的 Microsoft Entra 應用程式識別碼。
  • AZURE_TENANT_ID：Microsoft Entra 租用戶識別碼。
  • AZURE_FEDERATED_TOKEN_FILE：包含工作負載身分識別已簽署判斷提示的檔案，例如 Kubernetes 投射的服務帳戶 (JWT) 權杖。
  • AZURE_AUTHORITY_HOST：Microsoft Entra 授權單位的基底 URL。 例如： https://login.microsoftonline.com/ 。

您可以使用工作負載身分識別 (部分機器翻譯)，從 GitHub 或 ArgoCD 等 CI/CD 系統存取 Kubernetes 叢集，而不需將服務主體認證儲存在外部系統中。 若要從 GitHub 設定 OpenID Connect (OIDC) 同盟，請參閱 OIDC 同盟範例 (英文)。

下列範例示範如何使用工作負載身分識別：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

執行此 kubectl 命令來取得節點資訊：

kubectl get nodes

如何搭配 AKS 使用 kubelogin

AKS 使用一對第一方 Microsoft Entra 應用程式。 這些應用程式識別碼在所有環境中都相同。

伺服器端使用的 AKS Microsoft Entra 伺服器應用程式識別碼是 6dae42f8-4368-4678-94ff-3960e28e3630。 存取 AKS 叢集的存取權杖必須是針對此應用程式發出的。 在大部分的 kubelogin 驗證方法中，您必須使用 --server-id 搭配 kubelogin get-token。

kubelogin 用來代表使用者執行公用用戶端驗證的 AKS Microsoft Entra 用戶端應用程式識別碼是 80faf920-1908-4b52-b5ef-a8e7bedfc67a。 用戶端應用程式識別碼會用於裝置代碼和網頁瀏覽器互動式驗證方法中。

相關內容