Create an OpenID Connect provider on Azure Kubernetes Service (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 your OAuth-enabled applications, on your Azure Kubernetes Service (AKS) cluster, by using a security token called an ID token. With your AKS cluster, you can enable OpenID Connect (OIDC) Issuer, which allows Microsoft Entra ID or other cloud provider identity and access management platform, to discover the API server's public signing keys.
AKS rotates the key automatically and periodically. If you don't want to wait, you can rotate the key manually and immediately. The maximum lifetime of the token issued by the OIDC provider is one day.
Warning
Enable OIDC Issuer on existing cluster changes the current service account token issuer to a new value, which can cause down time as it restarts the API server. If your application pods using a service token remain in a failed state after you enable the OIDC Issuer, we recommend you manually restart the pods.
In this article, you learn how to create, update, and manage the OIDC Issuer for your cluster.
Important
After enabling OIDC issuer on the cluster, it's not supported to disable it.
Important
The token needs to be refreshed periodically. If you use SDK, the rotation is automatic, otherwise, you need to refresh the token every 24 hours manually.
Prerequisites
- The Azure CLI version 2.42.0 or higher. Run
az --version
to find your version. If you need to install or upgrade, see Install Azure CLI. - AKS supports OIDC Issuer on version 1.22 and higher.
Create an AKS cluster with OIDC Issuer
You can create an AKS cluster using the az aks create command with the --enable-oidc-issuer
parameter to use the OIDC Issuer. The following example creates a cluster named myAKSCluster with one node in the myResourceGroup:
az aks create -g myResourceGroup -n myAKSCluster --node-count 1 --enable-oidc-issuer
Update an AKS cluster with OIDC Issuer
You can update an AKS cluster using the az aks update command with the --enable-oidc-issuer
parameter to use the OIDC Issuer. The following example updates a cluster named myAKSCluster:
az aks update -g myResourceGroup -n myAKSCluster --enable-oidc-issuer
Show the OIDC Issuer URL
To get the OIDC Issuer URL, run the az aks show command. Replace the default values for the cluster name and the resource group name.
az aks show -n myAKScluster -g myResourceGroup --query "oidcIssuerProfile.issuerUrl" -otsv
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
To rotate the OIDC key, run the az aks oidc-issuer command. Replace the default values for the cluster name and the resource group name.
az aks oidc-issuer rotate-signing-keys -n myAKSCluster -g myResourceGroup
Important
Once you rotate the key, the old key (key1) expires after 24 hours. This means that both the old key (key1) and the new key (key2) are valid within the 24-hour period. If you want to invalidate the old key (key1) immediately, you need to rotate the OIDC key twice and restart the pods using projected service account tokens. Then key2 and key3 are valid, and key1 is invalid.
Check the OIDC keys
Get the OIDC Issuer URL
To get the OIDC Issuer URL, run the az aks show command. Replace the default values for the cluster name and the resource group name.
az aks show -n myAKScluster -g myResourceGroup --query "oidcIssuerProfile.issuerUrl" -otsv
The output should resemble the following:
https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/
By default, the Issuer is set to use the base URL https://{region}.oic.prod-aks.azure.com/{uuid}
, where the value for {region}
matches the location the AKS cluster is deployed in. The value {uuid}
represents the OIDC key, which is a randomly generated guid for each cluster that is immutable.
Get the discovery document
To get the discovery document, copy the URL https://(OIDC issuer URL).well-known/openid-configuration
and open it in browser.
The output should resemble the following:
{
"issuer": "https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/",
"jwks_uri": "https://eastus.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
To get the JWK Set document, copy the jwks_uri
from the discovery document and past it in your browser's address bar.
The output should resemble the following:
{
"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"
}
]
}
During key rotation, there's one other key present in the discovery document.
Next steps
- See configure creating a trust relationship between an app and an external identity provider to understand how a federated identity credential creates a trust relationship between an application on your cluster and an external identity provider.
- Review Microsoft Entra Workload ID (preview). This authentication method integrates with the Kubernetes native capabilities to federate with any external identity providers on behalf of the application.
- See Secure pod network traffic to understand how to use the Network Policy engine and create Kubernetes network policies to control the flow of traffic between pods in AKS.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for