你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
使用 kubelogin 对 Azure Kubernetes 服务中的用户进行身份验证
Azure 中的 kubelogin 插件是一个实现 Microsoft Entra 身份验证的 client-go 凭据插件。 kubelogin 插件提供 kubectl 命令行工具中没有的功能。 有关详细信息,请参阅 kubelogin 简介和 kubectl 简介。
与 Microsoft Entra ID 集成并运行 Kubernetes 版本 1.24 或更高版本的 Azure Kubernetes 服务 (AKS) 群集会自动使用 kubelogin 格式。
本文提供了有关如何将 kubelogin 用于 AKS 中所有受支持的 Microsoft Entra 身份验证方法的概述和示例。
限制
- 在 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 建立的登录上下文来获取访问令牌。 该令牌在与 az login
相同的 Microsoft Entra 租户中颁发。 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/
。
可以使用工作负载标识从 GitHub 或 ArgoCD 等 CI/CD 系统访问 Kubernetes 群集,而无需在外部系统中存储服务主体凭据。 若要从 GitHub 配置 OpenID Connect (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-id
和 kubelogin get-token
。
kubelogin 用于代表用户执行公共客户端身份验证的 AKS Microsoft Entra 客户端应用程序 ID 为 80faf920-1908-4b52-b5ef-a8e7bedfc67a
。 客户端应用程序 ID 用于设备代码和 Web 浏览器交互式身份验证方法。
相关内容
- 有关如何将 AKS 与 Microsoft Entra ID 集成,请阅读 AKS 托管的 Microsoft Entra ID 集成操作说明文章。
- 要开始使用 AKS 中的托管标识,请参阅使用 AKS 中的托管标识。
- 若要在 AKS 中开始使用工作负载标识,请参阅在 AKS 中使用工作负载标识。