在 Azure Kubernetes 服务 (AKS) 上创建 OpenID Connect 提供程序

本文介绍如何为 Azure Kubernetes 服务（AKS）群集创建和管理 OpenID Connect （OIDC）提供程序。 OIDC 颁发者允许 AKS 群集与标识提供者（如 Microsoft Entra ID）集成，为群集中运行的应用程序启用安全身份验证和单一登录（SSO）功能。

关于 AKS 上的 OpenID Connect （OIDC）

OpenID Connect (OIDC) 扩展了 OAuth 2.0 授权协议，以用作 Microsoft Entra ID 颁发的其他身份验证协议。可以使用 OIDC 在 Azure Kubernetes 服务（AKS）群集上使用名为 ID 令牌的安全令牌在已启用 OAuth 的应用程序之间启用单一登录（SSO）。可以在 AKS 群集上启用 OIDC 颁发者，该群集允许Microsoft Entra ID（或其他云提供商的标识和访问管理平台）来发现 API 服务器的公钥签名密钥。

先决条件

平台要求：

Azure CLI 版本 2.42.0+ （az --version 如果需要，请检查版本、安装或升级 Azure CLI ）
最低 Kubernetes 版本为 1.22+

特定于版本的行为：

Kubernetes 1.34+ 版本默认启用 OIDC 发行者（无需 --enable-oidc-issuer 标志）
Kubernetes 版本 1.30.0+ 的令牌自动续期已禁用--service-account-extend-token-expiration=false
如果 Kubernetes 版本低于 1.34 且之前未配置手动启用，则需要手动启用

重要注意事项：

一旦启用 OIDC 颁发者，就无法禁用
在现有集群上启用 OIDC 发行者需要重启 API 服务器（会导致短时间的停机）
最大令牌生存期为 24 小时（一天）
Kubernetes 1.30+ 群集所需的投射服务账户令牌

创建使用 OIDC 颁发者的 AKS 群集

使用带有参数的az aks create--enable-oidc-issuer命令创建 AKS 群集。

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>

# Create the AKS cluster with OIDC issuer enabled (OIDC issuer enabled by default for Kubernetes 1.34+)
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --node-count 1 \
    --enable-oidc-issuer \
    --generate-ssh-keys

在现有 AKS 集群上启用 OIDC 颁发者

使用 az aks update 命令和 --enable-oidc-issuer 参数在现有 AKS 群集上启用 OIDC 颁发者。

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>

# Enable the OIDC issuer on the existing AKS cluster
az aks update \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --enable-oidc-issuer

获取 OIDC 颁发者 URL

使用 az aks show 命令获取 OIDC 颁发者 URL。

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>

# Get the OIDC issuer URL
az aks show \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --query "oidcIssuerProfile.issuerUrl" \
    -o tsv

默认情况下，颁发者设置为使用基 URL https://{region}.oic.prod-aks.azure.com，其中 {region} 的值与部署 AKS 群集的位置相匹配。

轮换 OIDC 密钥

重要

轮换 OIDC 密钥时，请记住以下注意事项：

如果要在密钥轮换后立即使旧密钥失效，则必须轮换 OIDC 密钥两次，并使用投影的服务帐户令牌重启 Pod。
旧密钥和新密钥在轮换后仍有效 24 小时。
手动令牌刷新需要每 24 小时（除非使用 Azure 标识 SDK，它会自动轮换）。

使用 az aks oidc-issuer 命令轮换 OIDC 密钥。

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>

# Rotate the OIDC signing keys
az aks oidc-issuer rotate-signing-keys \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP

获取发现文档

在浏览器中导航到 OIDC 颁发者 URL，在 URL 末尾添加 /.well-known/openid-configuration。例如： https://eastus.oic.prod-aks.azure.com/.well-known/openid-configuration。

输出应类似于以下示例输出：

{
  "issuer": "https://chinaeast2.oic.prod-aks.azure.com/ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0/00000000-0000-0000-0000-000000000000/",
  "jwks_uri": "https://chinaeast2.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/openid/v1/jwks",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

获取 JWK 集文档

在浏览器中从发现文档导航到jwks_uri。例如： https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/openid/v1/jwks。

输出应类似于以下示例输出：
```
{
  "keys": [
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "xxx",
      "alg": "RS256",
      "n": "xxxx",
      "e": "AQAB"
    },
    {
      "use": "sig",
      "kty": "RSA",
      "kid": "xxx",
      "alg": "RS256",
      "n": "xxxx",
      "e": "AQAB"
    }
  ]
}
```
注释

在密钥轮换期间，发现文档中存在一个其他密钥。

Last updated on 2026-01-23

通过