使用 kubelogin 对 Azure Kubernetes 服务（AKS）中的用户进行身份验证

Azure 中的 kubelogin 插件是一个实现 Microsoft Entra 身份验证的 client-go 凭据插件。 kubelogin 插件提供 kubectl 命令行工具中没有的功能。有关详细信息，请参阅 kubelogin 简介和 kubectl 简介。

本文概述了适用于 AKS 推荐的受支持 Microsoft Entra 身份验证方法的 kubelogin 用法，并提供了相关示例。

AKS 限制中的 Kubelogin 身份验证

在 Microsoft Entra 中创建的组仅通过其 ObjectID 值（而不是显示名称）包含。 sAMAccountName 命令仅适用于从本地 Windows Server Active Directory 同步的组。

服务主体身份验证方法仅适用于托管Microsoft Entra ID集成，而不适用于旧版Microsoft Entra ID集成。
服务主体最多可以是 200 个 Microsoft Entra 组的成员。如果有超过 200 个组，请考虑使用应用程序角色。

在 Microsoft Entra 租户上设置 Microsoft Entra 条件访问策略时，无法使用设备代码身份验证方法。在这种情况下，请改用 Web 浏览器交互式身份验证。

Azure CLI 身份验证方法仅适用于 Microsoft Entra。

kubelogin 身份验证在 AKS 中的工作原理

运行 Kubernetes 版本 1.24 或更高版本的 AKS 群集会自动使用 kubelogin exec 插件格式。运行低于 1.24 的 Kubernetes 版本的群集需要手动转换为此格式。

对于与 kubelogin 的大多数交互，请使用 convert-kubeconfig 子命令。子命令使用你在环境变量中指定的 --kubeconfigKUBECONFIG kubeconfig 文件，根据指定的身份验证方法将最终的 kubeconfig 文件转换为 exec 格式。

kubelogin 实现的身份验证方法是 Microsoft Entra OAuth 2.0 令牌授予流。缓存行为取决于身份验证方法。设备代码、Web 浏览器交互式身份验证和资源所有者密码凭据 (ROPC) 身份验证会将身份验证记录缓存在 kubelogin 缓存目录中。 Azure CLI 和 Azure Developer CLI 等方法使用的是由各自命令行工具管理的缓存，而不是 kubelogin 缓存。

设备代码身份验证

设备代码是 convert-kubeconfig 子命令的默认身份验证方法。此身份验证方法会提示用户提供设备代码以从浏览器会话登录。

注意

在引入 kubelogin 和 exec 插件之前，kubectl 中的 Azure 身份验证方法仅支持设备代码流。它使用了一个较早版本的库，该库生成的令牌包含一个带有audience前缀的spn:声明。它与Microsoft Entra不兼容，后者使用代表（OBO）流。运行 convert-kubeconfig 子命令时，kubelogin 会从受众声明中删除 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 不会将令牌写入令牌缓存文件，因为 Azure CLI 已管理令牌。

Azure CLI 身份验证的参数

下表概述了可用于 Azure CLI 身份验证的参数：

参数	Description
`-l azurecli`	指定 kubelogin 身份验证方法。
`--azure-config-dir`	指定 Azure CLI 配置目录。默认目录为 ${HOME}/.azure。

使用az login命令登录到Azure。

az login

Web 浏览器交互式身份验证

Web 浏览器交互式（命令： -l interactive）身份验证方法会自动打开 Web 浏览器以登录用户。用户进行身份验证后，浏览器会使用已验证的凭据重定向到本地 Web 服务器。此身份验证方法符合条件访问策略。

可以将持有者令牌或所有权证明（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（客户端 ID）。
`--client-secret`	服务主体的客户端密钥。

托管标识身份验证

使用托管标识身份验证方法（命令：-l msi），以便应用程序连接到支持 Microsoft Entra 身份验证的资源。示例包括访问Azure资源，例如Azure虚拟机（VM）、虚拟机规模集或Azure Cloud Shell。

可以使用分配给资源的默认托管标识或特定用户分配的托管标识。

托管标识身份验证的参数

可用以下参数进行托管标识身份验证，详情见下表：

参数	Description
`-l msi`	指定 kubelogin 身份验证方法。
`--client-id`	用户分配的托管标识的应用程序 ID（客户端 ID）。如果未指定此参数，将使用默认托管标识。

工作负载身份验证

工作负荷标识（命令： -l workloadidentity）身份验证方法使用与 Microsoft Entra 联合的标识凭据对 AKS 群集的访问权限进行身份验证。该方法使用 Microsoft Entra 集成身份验证。它的工作原理是设置以下环境变量：

Variable	Description
`AZURE_CLIENT_ID`	与工作负荷标识联合的 Microsoft Entra 应用程序 ID。
`AZURE_TENANT_ID`	Microsoft Entra 租户 ID。
`AZURE_FEDERATED_TOKEN_FILE`	包含已签名工作负荷身份断言的文件，例如 Kubernetes 投射服务帐户（JWT 令牌）。
`AZURE_AUTHORITY_HOST`	Microsoft Entra 授权服务器的基础 URL。例如 `https://login.partner.microsoftonline.cn/`。

可以使用工作负荷标识从 CI/CD 系统（如 GitHub 或 Argo CD）访问 Kubernetes 群集，而无需在外部系统中存储服务主体凭据。若要从 GitHub 配置 OpenID Connect (OIDC) 联合，请参阅 OIDC 联合示例。

工作负载身份验证参数

下表概述了可用于工作负荷标识身份验证的参数：

参数	Description
`-l workloadidentity`	指定 kubelogin 身份验证方法。

Azure开发人员 CLI 身份验证

Azure开发人员 CLI（命令：-l azd）身份验证方法使用Azure开发人员 CLI 建立的已登录上下文来获取访问令牌。该令牌在与 azd auth login 相同的 Microsoft Entra 租户中颁发。 kubelogin 不会将令牌写入其令牌缓存，因为Azure开发人员 CLI 管理令牌。

此身份验证方法仅适用于 AKS 中托管的 Microsoft Entra。有关详细信息，请参阅Azure开发人员 CLI 概述。

Azure Pipelines 身份验证

Azure Pipelines（命令：-l azurepipelines）身份验证方法使用Azure 资源管理器服务连接和管道的系统访问令牌进行身份验证。此方法仅适用于Azure Pipelines。管道必须具有Azure 资源管理器服务连接，并允许脚本访问 OAuth 令牌。

当你将 AzureCLI@2 任务与 Azure 资源管理器服务连接一起使用时，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文件转换为使用exec插件，以实现所选身份验证方法。

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"

convert-kubeconfig运行子命令以转换 kubeconfig 文件以使用 exec 插件。
```
kubelogin convert-kubeconfig -l spn
```

为客户端 ID 和客户端机密或客户端证书设置环境变量。例如：

export AZURE_CLIENT_ID=<service-principal-client-id>
export AZURE_CLIENT_SECRET=<service-principal-client-secret>

注意

命令行参数方法将机密存储在 kubeconfig 文件中。

使用客户端 ID 和客户端机密或客户端证书参数运行 convert-kubeconfig 子命令。

kubelogin convert-kubeconfig -l spn --client-id <service-principal-client-id> --client-secret <service-principal-client-secret>

convert-kubeconfig运行子命令以转换 kubeconfig 文件以使用 exec 插件。
```
kubelogin convert-kubeconfig -l spn
```

为客户端 ID、客户端证书路径和客户端证书密码设置环境变量。例如：

export AZURE_CLIENT_ID=<service-principal-client-id>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<pfx-password>

convert-kubeconfig运行子命令以转换 kubeconfig 文件以使用 exec 插件。

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

为客户端 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 开发人员 CLI 转换 kubeconfig 文件

使用 Azure 开发人员 CLI 登录。
```
azd auth login
```
将 kubeconfig 文件转换为使用Azure开发人员 CLI 身份验证方法。
```
kubelogin convert-kubeconfig -l azd
```

在 Azure Pipelines 中转换 kubeconfig 文件

在使用 Azure 资源管理器服务连接的 AzureCLI@2 任务中，将 kubeconfig 文件转换为使用 Azure Pipelines 身份验证。

kubelogin convert-kubeconfig -l azurepipelines

删除缓存的令牌

使用 kubelogin remove-cache-dir 命令删除缓存的令牌。

kubelogin remove-cache-dir

获取节点信息

使用 kubectl get 命令获取节点信息。

kubectl get nodes

如何将 kubelogin 应用程序 ID 与 AKS 配合使用

AKS 使用一对第一方 Microsoft Entra 应用程序。这些应用程序 ID 在所有环境中都是相同的。

Application	应用程序 ID (GUID)	适用范围
AKS 服务器应用程序（`--server-id`）	`6dae42f8-4368-4678-94ff-3960e28e3630`	访问 AKS 时所有受支持的 kubelogin 身份验证方法的令牌受众。
AKS 公共客户端应用程序（`--client-id`）	`80faf920-1908-4b52-b5ef-a8e7bedfc67a`	设备代码、Web 浏览器交互式身份验证和 ROPC 身份验证。

当你直接为 AKS 调用时，请使用指定 AKS 服务器应用程序 ID。有关模式特定参数，请参阅 kubelogin get-token 参考文档。

注意

本节中的 AKS 公共客户端应用程序 ID 是用于设备代码、Web 浏览器交互式身份验证和 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>

了解如何在 Microsoft Entra 集成指南中将 AKS 与 Microsoft Entra 结合。
要开始使用 AKS 中的托管标识，请参阅使用 AKS 中的托管标识。
若要在 AKS 中开始使用工作负载标识，请参阅在 AKS 中使用工作负载标识。

Last updated on 2026-09-18