搭配 Azure Kubernetes Service (AKS) 使用 Microsoft Entra 工作負載識別碼

部署於 Azure Kubernetes Services (AKS) 叢集的工作部署必須利用 Microsoft Entra 應用程式認證或受控識別，才能存取 Microsoft Entra 的受保護資源，例如 Azure Key Vault 與 Microsoft Graph。 Microsoft Entra 工作負載識別碼會與 Kubernetes 原生功能整合，以與外部身分識別提供者同盟。

Microsoft Entra 工作負載識別碼可利用服務帳戶權杖磁碟區投影功能，支援 Pod 使用 Kubernetes 身分識別 (即服務帳戶)。 發行 Kubernetes 權杖後，OIDC 同盟會允許 Kubernetes 應用程式使用以註解式服務帳戶為基礎的 Microsoft Entra ID，以安全存取 Azure 資源。

如果您使用應用程式註冊，則 Microsoft Entra 工作負載識別碼特別適合搭配使用 Azure 身分識別用戶端程式庫 和 Microsoft 驗證程式庫 (MSAL) 集合。 您的工作負載可以使用上述任何程式庫，順暢地驗證和存取 Azure 雲端資源。

此文章可協助您了解這個新的驗證功能，並認識可用於規劃專案策略，以及從 Microsoft Entra Pod 受控識別進行移轉的選項。

注意

除了手動設定所有步驟，還有另一個稱為 Service 連線 or 的實作可協助您自動設定某些步驟。 另請參閱：什麼是服務 連線 或？

相依性

• AKS 支援 1.22 版和更新版本的 Microsoft Entra 工作負載識別碼。
• Azure CLI 2.47.0 版或更新版本。 執行 az --version 以尋找版本，然後執行 az upgrade 以升級版本。 如果您需要安裝或升級，請參閱安裝 Azure CLI。

Azure 身分識別用戶端程式庫

請在 Azure 身分識別用戶端程式庫中，選擇下列其中一種方式：

• 使用會嘗試使用 WorkloadIdentityCredential 的 DefaultAzureCredential。
• 建立包含 WorkloadIdentityCredential 的 ChainedTokenCredential 執行個體。
• 直接使用 WorkloadIdentityCredential。

下表列出了各語言生態系統客戶端程式庫所需的最低套件版本。

生態系統	程式庫	最小版本
.NET	Azure.Identity	1.9.0
C++	azure-identity-cpp	1.6.0
Go	azidentity	1.3.0
Java	azure-identity	1.9.0
Node.js	@azure/identity	3.2.0
Python	azure-identity	1.13.0

下列程式碼範例使用了 DefaultAzureCredential。 此認證會使用 Azure 工作負載身分識別變動 Webhook 插入的環境變數，以利用 Azure Key Vault 進行驗證。

.NET

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

string keyVaultUrl = Environment.GetEnvironmentVariable("KEYVAULT_URL");
string secretName = Environment.GetEnvironmentVariable("SECRET_NAME");

var client = new SecretClient(
    new Uri(keyVaultUrl),
    new DefaultAzureCredential());

KeyVaultSecret secret = await client.GetSecretAsync(secretName);

C++

#include <cstdlib>
#include <azure/identity.hpp>
#include <azure/keyvault/secrets/secret_client.hpp>

using namespace Azure::Identity;
using namespace Azure::Security::KeyVault::Secrets;

int main()
{
  const char* keyVaultUrl = std::getenv("KEYVAULT_URL");
  const char* secretName = std::getenv("SECRET_NAME");
  auto credential = std::make_shared<DefaultAzureCredential>();

  SecretClient client(keyVaultUrl, credential);
  Secret secret = client.GetSecret(secretName).Value;

  return 0;
}

Go

package main

import (
	"context"
	"os"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets"
    "k8s.io/klog/v2"
)

func main() {
	keyVaultUrl := os.Getenv("KEYVAULT_URL")
	secretName := os.Getenv("SECRET_NAME")

	credential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		klog.Fatal(err)
	}

	client, err := azsecrets.NewClient(keyVaultUrl, credential, nil)
	if err != nil {
		klog.Fatal(err)
	}

	secret, err := client.GetSecret(context.Background(), secretName, "", nil)
	if err != nil {
		klog.ErrorS(err, "failed to get secret", "keyvault", keyVaultUrl, "secretName", secretName)
		os.Exit(1)
	}
}

Java

import java.util.Map;

import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.DefaultAzureCredential;

public class App {
    public static void main(String[] args) {
        Map<String, String> env = System.getenv();
        String keyVaultUrl = env.get("KEYVAULT_URL");
        String secretName = env.get("SECRET_NAME");

        SecretClient client = new SecretClientBuilder()
                .vaultUrl(keyVaultUrl)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();
        KeyVaultSecret secret = client.getSecret(secretName);
    }
}

Node.js

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const main = async () => {
    const keyVaultUrl = process.env["KEYVAULT_URL"];
    const secretName = process.env["SECRET_NAME"];

    const credential = new DefaultAzureCredential();
    const client = new SecretClient(keyVaultUrl, credential);

    const secret = await client.getSecret(secretName);
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Python

import os

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

def main():
    keyvault_url = os.getenv('KEYVAULT_URL', '')
    secret_name = os.getenv('SECRET_NAME', '')

    client = SecretClient(vault_url=keyvault_url, credential=DefaultAzureCredential())
    secret = client.get_secret(secret_name)

if __name__ == '__main__':
    main()

Microsoft Authentication Library (MSAL)

下列用戶端程式庫為所需的最低版本。

生態系統	程式庫	映像	範例	具有 Windows
.NET	Microsoft Authentication Library-for-dotnet	ghcr.io/azure/azure-workload-identity/msal-net:latest	連結	Yes
Go	Microsoft Authentication Library-for-go	ghcr.io/azure/azure-workload-identity/msal-go:latest	連結	Yes
Java	Microsoft Authentication Library-for-java	ghcr.io/azure/azure-workload-identity/msal-java:latest	連結	No
JavaScript	Microsoft Authentication Library-for-js	ghcr.io/azure/azure-workload-identity/msal-node:latest	連結	No
Python	Microsoft Authentication Library-for-python	ghcr.io/azure/azure-workload-identity/msal-python:latest	連結	No

限制

• 每個受控識別只能有 20 個同盟身分識別認證。
• 一開始新增之後，同盟身分識別認證需要幾秒鐘的時間才能散佈。
• 不支援以開放原始碼專案 Virtual Kubelet 為基礎的虛擬節點附加元件。
• 在這些區域中，使用者指派的受控識別上無法建立同盟身分識別認證。

運作方式

在此安全性模型中，AKS 叢集會做為權杖簽發者，Microsoft Entra ID 會使用 OpenID Connect 來探索公開簽署金鑰，並在交換服務帳戶權杖做為 Microsoft Entra 權杖之前驗證服務帳戶權杖的真確性。 您的工作負載可以使用 Azure 身分識別用戶端程式庫或 Microsoft 驗證程式庫，將投影到其磁碟區的服務帳戶權杖交換為 Microsoft Entra 權杖。

下表說明 Microsoft Entra 工作負載識別碼所需的 OIDC 簽發者端點：

端點	描述
{IssuerURL}/.well-known/openid-configuration	也稱為 OIDC 探索文件。 這包含簽發者設定的相關中繼資料。
{IssuerURL}/openid/v1/jwks	這包括 Microsoft Entra ID 用來驗證服務帳戶權杖真實性的公開簽署金鑰。

下圖摘要說明使用 OpenID Connect 的驗證順序。

Webhook 憑證自動輪替

類似於其他 Webhook 附加元件，憑證會透過叢集憑證自動輪替作業進行輪替。

服務帳戶標籤和註釋

Microsoft Entra 工作負載識別碼支援下列與服務帳戶相關的對應：

• 一對一，其中服務帳戶會參考 Microsoft Entra 物件。
• 多對一，其中多個服務帳戶會參考相同的 Microsoft Entra 物件。
• 一對多，其中服務帳戶會透過變更用戶端識別碼註釋來參考多個 Microsoft Entra 物件。 如需詳細資訊，請參閱 如何將多個身分識別與 Kubernetes 服務帳戶建立同盟。

注意

如果服務帳戶註釋已更新，您必須重新啟動 Pod，變更才會生效。

如果您使用 Microsoft Entra Pod 受控識別，請將服務帳戶視為 Azure 身分識別，但服務帳戶屬於核心 Kubernetes API 的一部分，而不是自訂資源定義 (CRD)。 下列說明可用標籤和註釋的清單，其可用來在將服務帳戶權杖交換為 Microsoft Entra 存取權杖時設定行為。

服務帳戶註釋

所有註釋都為選用。 如果未指定註釋，則會使用預設值。

註釋	描述	預設
azure.workload.identity/client-id	代表與 Pod 一起使用的 Microsoft Entra 應用程式用戶端識別碼。 應用程式用戶端識別碼。
azure.workload.identity/tenant-id	代表 Azure AD 應用程式註冊 代表已註冊 Microsoft Entra 應用程式的 Azure 租用戶識別碼。	從 azure-wi-webhook-config ConfigMap 擷取的 AZURE_TENANT_ID 環境變數。
azure.workload.identity/service-account-token-expiration	代表投影服務帳戶權杖的 expirationSeconds 欄位。 其為您設定來防止在服務帳戶權杖重新整理 期間由錯誤所造成的停機時間。 Kubernetes 服務帳戶權杖到期與 Microsoft Entra 權杖無關。 Microsoft Entra 權杖在發行後的 24 小時後便會到期。	3600 支援的範圍是 3600-86400。

Pod 標籤

注意

針對使用工作負載身分識別的應用程式，必須在 Pod 規格中新增標籤 azure.workload.identity/use: "true"，以利 AKS 將工作負載身分識別移至 [失敗關閉] 情節，為必須使用工作負載身分識別的 Pod 提供一致且可靠的行為。 否則，Pod 會於重新啟動後失敗。

Label	描述	建議值	必要
azure.workload.identity/use	Pod 範本規格中須使用此標籤。僅具有此標籤的 Pod 會由 azure-workload-identity 變動許可 Webhook 進行變動，以插入 Azure 特定的環境變數和投影服務帳戶權杖磁碟區。	true	Yes

Pod 註釋

所有註釋都為選用。 如果未指定註釋，則會使用預設值。

註釋	描述	預設
azure.workload.identity/service-account-token-expiration	代表投影服務帳戶權杖的 expirationSeconds 欄位。 其為您設定來防止在服務帳戶權杖重新整理期間由錯誤所造成的停機時間。 Kubernetes 服務帳戶權杖到期與 Microsoft Entra 權杖無關。 Microsoft Entra 權杖在發行後的 24 小時後便會到期。 1	3600 支援的範圍是 3600-86400。
azure.workload.identity/skip-containers	表示要略過新增投影服務帳戶權杖磁碟區之容器的分號分隔清單。 例如： container1;container2 。	根據預設，如果服務帳戶標記為 azure.workload.identity/use: true，則會將投影服務帳戶權杖磁碟區新增至所有容器。
azure.workload.identity/inject-proxy-sidecar	將 Proxy init 容器和 Proxy Sidecar 插入 Pod。 Proxy Sidecar 可用來攔截對 IMDS 的權杖要求，並代表具有同盟身分識別認證的使用者取得 Microsoft Entra 權杖。	true
azure.workload.identity/proxy-sidecar-port	表示 Proxy Sidecar 的連接埠。	8000

¹ 如果服務帳戶也加上註釋，則優先使用。

如何移轉至工作負載身分識別

在執行 Pod 受控識別的叢集上，您可以將其設定為以使用兩種方法之一來使用工作負載身分識別。 第一個選項可讓您使用目前針對 Pod 受控識別實作的相同設定。 您只需要使用身分識別在命名空間內註釋服務帳戶，其可讓工作負載身分識別將註釋插入 Pod。

第二個選項是重寫您的應用程式，以使用最新版的 Azure 身分識別用戶端程式庫。

為了協助簡化移轉程序，我們開發了移轉 Sidecar，其能將您的應用程式所建立的 IMDS 交易轉換成 OpenID Connect (OIDC)。 移轉 Sidecar 並非長期解決方案，而是在工作負載身分識別上快速啟動並執行的方法。 在應用程式內執行移轉 Sidecar 會將應用程式 IMDS 交易 Proxy 至 OIDC。 替代方法是升級至支援的 Azure 身分識別用戶端程式庫版本，其支援 OIDC 驗證。

下表摘要說明我們針對工作負載身分識別的移轉或部署建議。

案例	描述
新的或現有的叢集部署執行支援的 Azure 身分識別用戶端程式庫版本	不需要執行任何移轉步驟。 範例部署資源： - 在新的叢集上部署和設定工作負載身分識別 - 教學課程：在 AKS 上搭配應用程式使用工作負載身分識別
新的或現有的叢集部署執行不支援的 Azure 身分識別用戶端程式庫版本	更新容器映像以使用支援的 Azure 身分識別 SDK 版本，或使用移轉 Sidecar。

下一步

• 若要了解如何設定 Pod 以使用工作負載身分識別作為移轉選項進行驗證，請參閱使用工作負載身分識別將應用程式驗證現代化。
• 請參閱教學課程使用工作負載身分識別搭配 Azure Kubernetes Service (AKS) 上的應用程式，其能協助您部署 Azure Kubernetes Service 叢集，並設定範例應用程式以使用工作負載身分識別。