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

This article describes how to create and manage an OpenID Connect (OIDC) provider for your Azure Kubernetes Service (AKS) cluster. The OIDC issuer allows your AKS cluster to integrate with identity providers like Microsoft Entra ID, enabling secure authentication and 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:

Version-specific behavior:

  • OIDC issuer enabled by default (no --enable-oidc-issuer flag needed) for Kubernetes version 1.34+
  • Token auto-extension disabled (--service-account-extend-token-expiration=false) for Kubernetes version 1.30.0+
  • Manual enablement required if not previously configured for Kubernetes version earlier than 1.34

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)
  • Projected service account tokens required for Kubernetes 1.30+ clusters

Create an AKS cluster with the OIDC issuer

  • Create an AKS 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 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

Enable the OIDC issuer on an existing AKS cluster

  • Enable the OIDC issuer on an existing AKS 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 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 is set to use the base URL https://{region}.oic.prod-aks.azure.com, where the value for {region} matches the location the AKS cluster is deployed in.

Rotate the OIDC key

Important

Keep the following considerations in mind when rotating the OIDC key:

  • 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.
  • Manual token refresh required every 24 hours (unless using Azure Identity SDK, which rotates 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

  • Navigate to your OIDC issuer URL in your browser and append /.well-known/openid-configuration to the URL. For 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

  • Navigate to the jwks_uri from the discovery document in your browser. For example: https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/openid/v1/jwks.

    Your output should resemble the following example output:

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

    Note

    During key rotation, there's one other key present in the discovery document.

Related content

  • Last updated on