Create an OpenID Connect issuer on Azure Kubernetes Service (AKS)

This article describes how to create and manage an OpenID Connect (OIDC) issuer for your Azure Kubernetes Service (AKS) cluster. The OIDC issuer enables your AKS cluster to integrate with identity providers like Microsoft Entra ID, so you can securely authenticate and provide single sign-on (SSO) capabilities for applications running within the cluster.

About OpenID Connect (OIDC) on AKS

OpenID Connect (OIDC) extends the OAuth 2.0 authorization protocol for use as another authentication protocol issued by Microsoft Entra ID. You can use OIDC to enable single sign-on (SSO) between OAuth-enabled applications on your Azure Kubernetes Service (AKS) cluster using a security token called an ID token. You can enable the OIDC issuer on your AKS clusters, which allows Microsoft Entra ID (or another cloud provider's identity and access management platform) to discover the API server's public signing keys.

Prerequisites

Platform requirements:

Azure CLI version 2.42.0 or later (az --version to check version, install or upgrade Azure CLI if needed).
Kubernetes version 1.22 or later.

Version-specific behavior (AKS Standard):

OIDC issuer is enabled by default (no --enable-oidc-issuer flag needed) for newly created AKS clusters on Kubernetes version 1.34 or later.
For existing clusters, OIDC isn't enabled by default regardless of Kubernetes version and requires manual enablement.
Token auto-extension disabled (--service-account-extend-token-expiration=false) for Kubernetes version 1.30.0 or later.
If OIDC issuer wasn't previously configured, manual enablement is required for Kubernetes versions earlier than 1.34.
Projected service account tokens are required for Kubernetes version 1.30 or later clusters.

Important considerations:

You can't disable OIDC issuer once enabled.
Enabling OIDC issuer on existing clusters requires API server restart (brief downtime).
Maximum token lifetime is 24 hours (one day).

Create an AKS cluster with the OIDC issuer

Create an AKS Standard cluster using the az aks create command with the --enable-oidc-issuer parameter.

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>
    
# Create the AKS Standard cluster with OIDC issuer enabled
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --node-count 1 \
    --enable-oidc-issuer \
    --generate-ssh-keys

Note

On AKS Standard clusters created with Kubernetes version 1.34 or later, the OIDC issuer is enabled by default for new clusters.

Enable OIDC issuer on an existing AKS Standard cluster

Enable the OIDC issuer on an existing AKS Standard cluster using the az aks update command with the --enable-oidc-issuer parameter.

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

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

Get the OIDC issuer URL

Get the OIDC issuer URL using the az aks show command.

# 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

By default, the issuer uses the base URL https://{region}.oic.prod-aks.azure.com, where the value for {region} matches the location where you deployed the AKS cluster.

Rotate the OIDC signing key

Important

Keep the following considerations in mind when rotating OIDC signing keys:

If you want to invalidate the old key immediately after key rotation, you must rotate the OIDC key twice and restart the pods using projected service account tokens.
Both old and new keys remain valid for 24 hours after rotation.
You need to refresh the token manually every 24 hours (unless you're using Azure Identity client libraries, which refresh automatically).

Rotate the OIDC key using the az aks oidc-issuer command.

# 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

Get the discovery document

Go to your OIDC issuer URL in your browser and add /.well-known/openid-configuration to the URL.

Example: https://eastus.oic.prod-aks.azure.com/.well-known/openid-configuration

Your output should resemble the following example output:

{
  "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"
  ]
}

Get the JWK Set document

In your browser, go to the jwks_uri from the discovery document.

For example: https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/openid/v1/jwks