你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将 Microsoft Entra 工作负载 ID 与 Azure Kubernetes 服务 (AKS) 配合使用

部署在 Azure Kubernetes 服务 (AKS) 群集上的工作负载需要使用 Microsoft Entra 应用程序凭据或托管标识才能访问由 Microsoft Entra 保护的资源，例如 Azure 密钥保管库和 Microsoft Graph。 Microsoft Entra 工作负载 ID与 Kubernetes 本机功能集成，以便与外部标识提供者联合。

Microsoft Entra 工作负载 ID 使用服务帐户令牌卷投影（即服务帐户），从而支持 Pod 使用 Kubernetes 标识。 将会颁发 Kubernetes 令牌，并且 OIDC 联合支持 Kubernetes 应用程序基于带注释的服务帐户使用 Microsoft Entra ID 安全地访问 Azure 资源。

Microsoft Entra 工作负载 ID 与应用程序注册结合使用，特别适用于 Azure 标识客户端库或 Microsoft 身份验证库 (MSAL) 集合。 工作负载可以使用其中任何一个库来无缝地进行身份验证和访问 Azure 云资源。

本文可帮助你了解 Microsoft Entra Workload ID，并回顾了可用于规划项目策略和从 Microsoft Entra Pod 托管标识进行可能的迁移的选项。

注意

可以使用服务连接器自动配置某些步骤。 另请参阅：什么是服务连接器？

依赖项

• AKS 支持版本 1.22 及更高版本的 Microsoft Entra 工作负载 ID。
• Azure CLI 版本 2.47.0 或更高版本。 可通过运行 az --version 查找版本，运行 az upgrade 升级版本。 如果需要进行安装或升级，请参阅安装 Azure CLI。

Azure 标识客户端库

在 Azure 标识客户端库中，选择以下方法之一：

• 使用 DefaultAzureCredential，它会尝试使用 WorkloadIdentityCredential。
• 创建包含 WorkloadIdentityCredential 的 ChainedTokenCredential 实例。
• 直接使用 WorkloadIdentityCredential。

下表提供了每种语言生态系统的客户端库所需的最低包版本。

生态系统	Library	最低版本
.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 身份验证库 (MSAL)

以下客户端库是所需的最低版本。

生态系统	Library	映像	示例	具有 Windows
.NET	Microsoft Authentication Library-for-dotnet	ghcr.io/azure/azure-workload-identity/msal-net:latest	链接	是
Go	Microsoft Authentication Library-for-go	ghcr.io/azure/azure-workload-identity/msal-go:latest	链接。	是
Java	Microsoft Authentication Library-for-java	ghcr.io/azure/azure-workload-identity/msal-java:latest	链接。	否
JavaScript	Microsoft Authentication Library-for-js	ghcr.io/azure/azure-workload-identity/msal-node:latest	链接。	否
Python	Microsoft Authentication Library-for-python	ghcr.io/azure/azure-workload-identity/msal-python:latest	链接。	否

限制

• 每个托管标识最多可以有 20 个联合标识凭据。
• 联合标识凭据在最初添加后需要几秒钟才能传播。
• 不支持基于开源项目 Virtual Kubelet 的虚拟节点加载项。
• 不支持对这些区域中的用户分配的托管标识创建联合标识凭据。

工作原理

在此安全模型中，AKS 群集充当令牌颁发者。 Microsoft Entra ID 使用 OpenID Connect 发现公共签名密钥，并在用它交换 Microsoft Entra 令牌前验证服务帐户令牌的真实性。 工作负载可以使用 Azure 标识客户端库或 Microsoft 身份验证库 (MSAL)，将投影到其卷的服务帐户令牌交换为 Microsoft Entra 令牌。

下表描述了 Microsoft Entra 工作负载 ID 所需的 OIDC 颁发者终结点：

终结点	说明
{IssuerURL}/.well-known/openid-configuration	也称为 OIDC 发现文档。 其中包含有关颁发者配置的元数据。
{IssuerURL}/openid/v1/jwks	这包含 Microsoft Entra 用于验证服务帐户令牌真实性的公共签名密钥。

下图汇总了使用 OpenID Connect 的身份验证顺序。

Webhook 证书自动轮换

与其他 Webhook 加载项类似，证书通过群集证书自动轮换操作进行轮换。

服务帐户标签和批注

Microsoft Entra 工作负载 ID 支持与服务帐户相关的以下映射：

• 一个服务帐户引用一个 Microsoft Entra 对象的一对一映射。
• 多个服务帐户引用同一 Microsoft Entra 对象的多对一映射。
• 一个服务帐户通过更改客户端 ID 注释来引用多个 Microsoft Entra 对象的一对多映射。 有关详细信息，请参阅如何将多个标识与 Kubernetes 服务帐户联合。

注意

如果服务帐户批注已更新，你必须重启 Pod 才能使更改生效。

如果你已使用 Microsoft Entra Pod 托管标识，则可将服务帐户视为 Azure 安全主体，只不过服务帐户是核心 Kubernetes API 的一部分，而不是自定义资源定义 (CRD)。 以下部分描述了可用标签和注释的列表，它们可用于配置在将服务帐户令牌交换为 Microsoft Entra 访问令牌时的行为。

服务帐户批注

所有注释都是可选的。 如果未指定注释，则将使用默认值。

注释	说明	默认
azure.workload.identity/client-id	表示 Microsoft Entra 应用程序 Azure AD 应用程序客户端 ID。
azure.workload.identity/tenant-id	表示在其中注册了 Azure AD 应用程序的 Microsoft Entra 应用程序已注册。	AZURE_TENANT_ID 环境变量，从 azure-wi-webhook-config ConfigMap 提取。
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 特定环境变量和投影的服务帐户令牌卷。	是	是

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。	默认情况下，如果 Pod 带有 azure.workload.identity/use: true 标签，则投影的服务帐户令牌卷将添加到所有容器。
azure.workload.identity/inject-proxy-sidecar	将代理 init 容器和代理挎斗注入 Pod。 代理挎斗用于拦截对 IMDS 的令牌请求，并代表具有联合标识凭据的用户获取 Microsoft Entra 令牌。	是
azure.workload.identity/proxy-sidecar-port	表示代理挎斗的端口。	8000

¹ 当同时批注了服务帐户时优先。

如何迁移到 Microsoft Entra Workload ID

在已经运行 Pod 托管标识的群集上，可以通过两种方式之一将该群集配置为使用工作负载标识。 第一种做法允许使用为 Pod 托管标识实现的相同配置。 你可以在命名空间中使用标识批注服务帐户，以启用 Microsoft Entra Workload ID 并将批注注入 Pod。

第二种做法是重新编写应用程序，以使用最新版本的 Azure 标识客户端库。

为了帮助条理化和简化迁移过程，我们开发了一个迁移挎斗，它可以将应用程序产生的 IMDS 事务转换到 OpenID Connect (OIDC)。 迁移挎斗不旨在用作长期解决方案，而是一种快速启动和运行工作负载标识的方式。 在应用程序中运行迁移挎斗会将应用程序 IMDS 事务中转到 OIDC。 另一种方法是升级到支持 OIDC 身份验证的受支持 Azure 标识客户端库版本。

下表汇总了我们的工作负载标识迁移或部署建议。

方案	说明
新的或现有群集部署运行受支持版本的 Azure 标识客户端库	无需执行迁移步骤。 示例部署资源：在新群集上部署并配置工作负载标识
新的或现有群集部署运行不受支持版本的 Azure 标识客户端库	更新容器映像以使用受支持版本的 Azure 标识 SDK，或使用迁移挎斗。

后续步骤

• 若要了解如何将 Pod 设置为使用工作负载标识作为迁移选项进行身份验证，请参阅使用工作负载标识来现代化应用程序身份验证。
• 请参阅使用工作负载标识部署并配置 AKS 群集，该教程可帮助你部署 Azure Kubernetes 服务群集，并将示例应用程序配置为使用工作负载标识。