使用 kubelogin 在 Azure Kubernetes Service(AKS)中驗證使用者。

Azure 中的 kubelogin 外掛程式是一種 client-go 認證外掛程式,可實作 Microsoft Entra 驗證。 kubelogin 外掛程式提供 kubectl 命令列工具中未提供的功能。 如需詳細資訊,請參閱 kubelogin 簡介與 kubectl 簡介。

本文概述並示範如何使用 Kubelogin 來支援 AKS 的 Microsoft Entra 認證方法。

AKS 中 kubelogin 驗證的限制

  • 在 Microsoft Entra 中建立的群組僅以其 ObjectID 值來包含,而非顯示名稱。 sAMAccountName 命令僅適用於從內部部署 Windows Server Active Directory 同步的群組。
  • 服務主體認證方法僅適用於受管理的 Microsoft Entra ID 整合,無法支援舊有的 Microsoft Entra ID 整合。
  • 服務主體最多可成為 200 個 Microsoft Entra 群組的成員。 如果您有超過 200 個群組,請考慮使用應用程式角色。
  • 當 Microsoft Entra 租用戶上設定了 Microsoft Entra 條件式存取原則時,裝置代碼驗證方法將無法運作。 在這種情況下,建議改用網頁瀏覽器的互動式驗證。
  • Azure CLI 認證方法僅適用於 Microsoft Entra。

AKS 中 Kubelogin 認證的運作方式

運行 Kubernetes 1.24 或更新版本的 AKS 叢集會自動使用 kubelogin exec 外掛格式。 運行 Kubernetes 版本早於 1.24 的叢集需要手動轉換成此格式。

大多數與 kubelogin 互動時,請使用 convert-kubeconfig 子指令。 這個子指令會利用你在環境變數中--kubeconfigKUBECONFIG指定的 kubeconfig 檔案,根據指定的認證方法,將最終的 kubeconfig 檔案轉換成執行格式。

kubelogin 所實作的驗證方法為 Microsoft Entra OAuth 2.0 權杖授權流程。 快取行為視認證方式而定。 裝置程式碼、互動式網頁瀏覽器,以及資源擁有者密碼認證(ROPC)的驗證快取記錄,皆會儲存在 kubelogin 快取目錄中。 像是 Azure CLI 和 Azure Developer CLI 這類方法,會使用由各自命令列工具管理的快取,而非 kubelogin 快取。

裝置程式碼驗證

裝置代碼是 convert-kubeconfig 子命令的預設驗證方法。 此驗證方法會提示使用者透過瀏覽器工作階段登入裝置代碼。

附註

在 kubelogin 與 exec 外掛程式推出之前,kubectl 中的 Azure 驗證方法僅支援裝置代碼流程。 該方法使用舊版程式庫,所產生的權杖其 audience 宣告具有 spn: 首碼。 它與 Microsoft Entra並不相容,因為後者使用的是代理 (OBO) 流程。 當您執行 convert-kubeconfig 子命令時,kubelogin 會從 audience 宣告中移除 spn: 首碼。

裝置碼驗證參數

下表列出可用於裝置碼驗證的參數:

參數 Description
-l devicecode (選用) 規定了 kubelogin 的認證方法。 此參數為可選,因為裝置程式碼是預設方法。
--legacy 對於已配置舊有 Microsoft Entra ID 整合的叢集,採用舊有行為。 如果 kubeconfig 檔是針對此類叢集,kubelogin 會自動加入該 --legacy 旗標。
--cache-dir 覆蓋標記快取目錄的預設路徑,該路徑為 ${HOME}/.kube/cache/kubelogin。

Azure CLI 驗證

Azure CLI(指令: -l azurecli)認證方法利用 Azure CLI 建立的登入上下文來取得存取權杖。 權杖會在與 az login 相同的 Microsoft Entra 租用戶中發行。 kubelogin 不會將 token 寫入到快取檔案中,因為 Azure CLI 已經負責管理這些檔案。

Azure CLI 認證的參數

下表列出你可以在 Azure CLI 認證中使用的參數:

參數 Description
-l azurecli 規定了 kubelogin 的認證方法。
--azure-config-dir 指定 Azure CLI 配置目錄。 預設目錄是 ${HOME}/.azure。

登入 Azure

請使用az login指令登入 Azure。

az login

網頁瀏覽器互動式認證

網頁瀏覽器的互動式(指令: -l interactive)認證方法會自動開啟瀏覽器以登入使用者。 使用者認證完成後,瀏覽器會利用驗證過的憑證重新導向到本地網頁伺服器。 此驗證方法符合條件式存取原則。

你可以使用持有人令牌或持有證明(PoP)令牌使用此認證方式。

持有憑證認證的參數

下表列出可用於持有人憑證認證的參數:

參數 Description
-l interactive 規定了 kubelogin 的認證方法。
--cache-dir 覆蓋標記快取目錄的預設路徑,該路徑為 ${HOME}/.kube/cache/kubelogin。

PoP 令牌認證參數

下表列出可用於 PoP 令牌驗證的參數:

參數 Description
-l interactive 規定了 kubelogin 的認證方法。
--pop-enabled 啟用 PoP 令牌認證。
--pop-claims 以索引鍵值配對格式指定 PoP 權杖宣告。 例如: u=/ARM/ID/OF/CLUSTER 。

服務主體驗證

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

服務主體認證的參數

下表概述可與服務主體認證搭配使用的參數:

參數 Description
-l spn 規定了 kubelogin 的認證方法。
--client-id 服務主體的應用程式 ID(client-id)。
--client-secret 服務主體的用戶端密鑰。

受控識別驗證

對於連接支援 Microsoft Entra 認證資源的應用程式,請使用 管理身份 (command: -l msi)認證方法。 例如存取 Azure 資源,如 Azure 虛擬機(VM)、虛擬機器擴展集 或 Azure Cloud Shell。

你可以使用資源所指派的預設管理身份,或是特定使用者指定的管理身份。

管理身份驗證的參數

下表列出可用於管理身份驗證的參數:

參數 Description
-l msi 規定了 kubelogin 的認證方法。
--client-id 使用者指派受控識別的應用程式識別碼 (client-id)。 如果你沒有指定這個參數,就會使用預設的管理身份。

工作負載身份驗證

工作負載身份(指令: -l workloadidentity)認證方法使用與 Microsoft Entra 聯合的身份憑證來驗證 AKS 叢集的存取權限。 此方法使用 Microsoft Entra 整合式驗證。 其運作方式為設定下列環境變數:

Variable Description
AZURE_CLIENT_ID 與工作負載識別聯合的 Microsoft Entra 應用程式識別碼。
AZURE_TENANT_ID Microsoft Entra 租戶識別碼。
AZURE_FEDERATED_TOKEN_FILE 包含工作負載識別已簽署判斷提示的檔案,例如 Kubernetes 投射的服務帳戶 (JWT) 權杖。
AZURE_AUTHORITY_HOST Microsoft Entra 權威機構的基底網址。 例如: https://login.microsoftonline.com/ 。

你可以使用工作負載身份,從像 GitHub 或 Argo CD 這類 CI/CD 系統存取 Kubernetes 叢集,而不必在外部系統中儲存服務主體憑證。 若要從 GitHub 設定 OpenID Connect (OIDC) 聯合,請參閱 OIDC 聯合範例。

工作負載身份驗證參數

下表列出可用於工作負載身份驗證的參數:

參數 Description
-l workloadidentity 規定了 kubelogin 的認證方法。

Azure Developer CLI 驗證

Azure 開發者 CLI(命令:-l azd)認證方法會利用 Azure 開發者 CLI 建立的登入上下文來取得存取權杖。 權杖會在與 azd auth login 相同的 Microsoft Entra 租用戶中發行。 kubelogin 不會將權杖寫入其權杖快取,因為 Azure 開發人員 CLI 負責管理這些權杖。

此驗證方法僅適用於 AKS 中受管理的 Microsoft Entra。 欲了解更多資訊,請參閱 Azure 開發者 CLI 總覽。

Azure Pipelines 驗證

Azure Pipelines(command: -l azurepipelines)認證方法使用Azure Resource Manager服務連線及管線的系統存取權杖來認證。 此方法僅適用於 Azure Pipelines。 管線必須有 Azure Resource Manager 服務連線,並允許腳本存取 OAuth 令牌。

當你使用AzureCLI@2帶有 Azure Resource Manager 服務連線的任務時,kubelogin 可以使用 Azure Pipelines 提供的租戶 ID、客戶端 ID 和服務連線 ID 作為環境變數。 欲了解更多資訊,請參閱 Azure Pipelines 服務連接。

Warning

KubeLogin 也支援資源擁有者密碼憑證(ROPC)認證方法。 Microsoft 建議不要使用 ROPC,因為它與多重身份驗證及某些混合身份情境不相容。 欲了解更多資訊,請參閱 Microsoft 身分識別平台 ROPC 指引。

匯出 kubeconfig 檔案路徑

執行 convert-kubeconfig 子指令前,先將 kubeconfig 檔案路徑匯出到 KUBECONFIG 環境變數。 例如:

export KUBECONFIG=/path/to/kubeconfig

轉換 kubeconfig 檔案

執行 convert-kubeconfig 子指令,將 kubeconfig 檔案轉換成你選擇的認證方法的執行插件。

kubelogin convert-kubeconfig
kubelogin convert-kubeconfig -l azurecli
# Bearer token authentication
kubelogin convert-kubeconfig -l interactive

# Proof-of-Possession (PoP) token authentication
kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"
  1. 執行 convert-kubeconfig 子指令將 kubeconfig 檔案轉換成執行插件。

    kubelogin convert-kubeconfig -l spn
    
  2. 設定客戶端 ID 和客戶端秘密或客戶端憑證的環境變數。 例如:

    export AZURE_CLIENT_ID=<service-principal-client-id>
    export AZURE_CLIENT_SECRET=<service-principal-client-secret>
    
# Default managed identity authentication
kubelogin convert-kubeconfig -l msi

# Specific managed identity authentication
kubelogin convert-kubeconfig -l msi --client-id <managed-identity-client-id>
kubelogin convert-kubeconfig -l workloadidentity

用 Azure Developer CLI 轉換 kubeconfig 檔案

  1. 請使用 Azure 開發者 CLI 登入。

    azd auth login
    
  2. 將 kubeconfig 檔案轉換成使用 Azure Developer CLI 認證方法。

    kubelogin convert-kubeconfig -l azd
    

在 Azure Pipelines 中轉換 kubeconfig 檔案

在使用 Azure Resource Manager 服務連線的AzureCLI@2任務中,將 kubeconfig 檔案轉換成使用 Azure Pipelines 認證。

kubelogin convert-kubeconfig -l azurepipelines

移除快取的詞元

使用 kubelogin remove-cache-dir 指令移除快取的標記。

kubelogin remove-cache-dir

取得節點資訊

透過指令 kubectl get 取得節點資訊。

kubectl get nodes

如何在 AKS 上使用 Kubelogin 應用程式 ID

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

Application 應用程式識別碼 (GUID) 用於
AKS 伺服器應用程式(--server-id) 6dae42f8-4368-4678-94ff-3960e28e3630 存取 AKS 時,所有支援的 kubelogin 驗證方法所使用的權杖對象。
AKS 公共客戶端應用程式(--client-id) 80faf920-1908-4b52-b5ef-a8e7bedfc67a 裝置程式碼、網頁瀏覽器互動式,以及 ROPC 認證。

當您直接針對 AKS 呼叫 kubelogin get-token 時,請使用 --server-id 指定 AKS 伺服器應用程式 ID。 關於模式特定的參數,請參見 kubelogin get-token 參考文獻。

附註

本節中的 AKS 公用用戶端應用程式 ID,是用於裝置代碼、網頁瀏覽器互動式驗證及 ROPC 驗證的 --client-id 值。 對於服務主體與受管理身份驗證,則 --client-id 會識別服務主體或使用者指派的管理身份。

例如,透過裝置代碼驗證以及 AKS 應用程式 ID 取得權杖:

kubelogin get-token \
    --login devicecode \
    --server-id 6dae42f8-4368-4678-94ff-3960e28e3630 \
    --client-id 80faf920-1908-4b52-b5ef-a8e7bedfc67a \
    --tenant-id <microsoft-entra-tenant-id>