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

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

  • 项目

Azure 中的 kubelogin 插件是实现 Microsoft Entra 身份验证的客户端 go 凭据 插件 。 kubelogin 插件提供 kubectl 命令行工具中不可用的功能。

与 Microsoft Entra ID 集成的 Azure Kubernetes 服务 （AKS） 群集，并运行 Kubernetes 版本 1.24 或更高版本会自动使用 kubelogin 格式。

本文概述了如何使用 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 条件访问策略时，设备代码身份验证方法不起作用。 在这种情况下，请使用 Web 浏览器交互式身份验证。

身份验证的工作原理

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

kubelogin 实现的身份验证方法是 Microsoft Entra OAuth 2.0 令牌授予流。 以下参数标志通常用于 kubelogin 子命令。 通常，从 AKS 获取 kubeconfig 文件时，这些标志已准备就绪。

  • --tenant-id：Microsoft Entra 租户 ID。
  • --client-id：公共客户端应用程序的应用程序 ID。 此客户端应用仅在设备代码、Web 浏览器交互和 OAuth 2.0 资源所有者密码凭据（ROPC）（工作流标识）登录方法中使用。
  • --server-id：Web 应用或资源服务器的应用程序 ID。 令牌将颁发给此资源。

注意

在每个身份验证方法中，令牌不会缓存在文件系统上。

身份验证方法

后续部分介绍支持的身份验证方法以及如何使用它们：

  • 设备代码
  • Azure CLI
  • Web 浏览器交互式
  • 服务主体
  • 托管标识
  • 工作负载标识

设备代码

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

在引入 kubelogin 和 exec 插件之前，kubectl 中的 Azure 身份验证方法仅支持设备代码流。 它使用了早期版本的库，该库生成具有前缀的声明spn:的audience令牌。 它与 AKS 托管的 Microsoft Entra ID 不兼容，它使用 代表 （OBO） 流。 运行 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 租户上配置条件访问策略时，设备代码登录方法不起作用。 在此方案中，请使用 Web 浏览器交互式方法。

Azure CLI

Azure CLI 身份验证方法使用 Azure CLI 建立的已登录上下文来获取访问令牌。 令牌在与 .. 的同一个 Microsoft Entra 租户 az login中颁发。 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 浏览器交互式

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

使用此方法进行身份验证时，访问令牌将缓存在 ${HOME}/.kube/cache/kubelogin 目录中。 可以使用参数替代此路径 --token-cache-dir 。

持有者令牌

以下示例演示如何将持有者令牌与 Web 浏览器交互流配合使用：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

运行此 kubectl 命令以获取节点信息：

kubectl get nodes

所有权证明令牌

以下示例演示如何将所有权证明（PoP）令牌与 Web 浏览器交互流配合使用：

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 应用程序 ID。
  • AZURE_TENANT_ID：Microsoft Entra 租户 ID。
  • AZURE_FEDERATED_TOKEN_FILE：包含工作负荷标识的已签名断言的文件，例如 Kubernetes 投影服务帐户 （JWT） 令牌。
  • AZURE_AUTHORITY_HOST：Microsoft Entra 颁发机构的基 URL。 例如 https://login.microsoftonline.com/。

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

以下示例演示如何使用工作负荷标识：

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

运行此 kubectl 命令以获取节点信息：

kubectl get nodes

如何将 kubelogin 与 AKS 配合使用

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

服务器端使用的 AKS Microsoft Entra 服务器应用程序 ID 为 6dae42f8-4368-4678-94ff-3960e28e3630。 必须为此应用程序颁发访问 AKS 群集的访问令牌。 在大多数 kubelogin 身份验证方法中，必须使用 --server-idkubelogin get-token.

kubelogin 用来代表用户执行公共客户端身份验证的 AKS Microsoft Entra 客户端应用程序 ID 是 80faf920-1908-4b52-b5ef-a8e7bedfc67a。 客户端应用程序 ID 用于设备代码和 Web 浏览器交互式身份验证方法。

相关内容