Use Microsoft Entra Workload ID with Azure Kubernetes Service (AKS)
Workloads deployed on an Azure Kubernetes Services (AKS) cluster require Microsoft Entra application credentials or managed identities to access Microsoft Entra protected resources, such as Azure Key Vault and Microsoft Graph. Microsoft Entra Workload ID integrates with the capabilities native to Kubernetes to federate with external identity providers.
Microsoft Entra Workload ID uses Service Account Token Volume Projection enabling pods to use a Kubernetes identity (that is, a service account). A Kubernetes token is issued and OIDC federation enables Kubernetes applications to access Azure resources securely with Microsoft Entra ID based on annotated service accounts.
Microsoft Entra Workload ID works especially well with the Azure Identity client libraries and the Microsoft Authentication Library (MSAL) collection if you're using application registration. Your workload can use any of these libraries to seamlessly authenticate and access Azure cloud resources.
This article helps you understand this new authentication feature, and reviews the options available to plan your project strategy and potential migration from Microsoft Entra pod-managed identity.
Dependencies
- AKS supports Microsoft Entra Workload ID on version 1.22 and higher.
- The Azure CLI version 2.47.0 or later. Run
az --version
to find the version, and runaz upgrade
to upgrade the version. If you need to install or upgrade, see Install Azure CLI.
Azure Identity client libraries
In the Azure Identity client libraries, choose one of the following approaches:
- Use
DefaultAzureCredential
, which attempts to use theWorkloadIdentityCredential
. - Create a
ChainedTokenCredential
instance that includesWorkloadIdentityCredential
. - Use
WorkloadIdentityCredential
directly.
The following table provides the minimum package version required for each language ecosystem's client library.
Ecosystem | Library | Minimum version |
---|---|---|
.NET | Azure.Identity | 1.9.0 |
C++ | azure-identity-cpp | 1.6.0 |
Go | azidentity | 1.3.0 |
Java | azure-identity | 1.9.0 |
Node.js | @azure/identity | 3.2.0 |
Python | azure-identity | 1.13.0 |
In the following code samples, DefaultAzureCredential
is used. This credential type uses the environment variables injected by the Azure Workload Identity mutating webhook to authenticate with Azure Key Vault.
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
string keyVaultUrl = Environment.GetEnvironmentVariable("KEYVAULT_URL");
string secretName = Environment.GetEnvironmentVariable("SECRET_NAME");
var client = new SecretClient(
new Uri(keyVaultUrl),
new DefaultAzureCredential());
KeyVaultSecret secret = await client.GetSecretAsync(secretName);
Microsoft Authentication Library (MSAL)
The following client libraries are the minimum version required.
Ecosystem | Library | Image | Example | Has Windows |
---|---|---|---|---|
.NET | Microsoft Authentication Library-for-dotnet | ghcr.io/azure/azure-workload-identity/msal-net:latest |
Link | Yes |
Go | Microsoft Authentication Library-for-go | ghcr.io/azure/azure-workload-identity/msal-go:latest |
Link | Yes |
Java | Microsoft Authentication Library-for-java | ghcr.io/azure/azure-workload-identity/msal-java:latest |
Link | No |
JavaScript | Microsoft Authentication Library-for-js | ghcr.io/azure/azure-workload-identity/msal-node:latest |
Link | No |
Python | Microsoft Authentication Library-for-python | ghcr.io/azure/azure-workload-identity/msal-python:latest |
Link | No |
Limitations
- You can only have 20 federated identity credentials per managed identity.
- It takes a few seconds for the federated identity credential to be propagated after being initially added.
- Virtual nodes add on, based on the open source project Virtual Kubelet, isn't supported.
- Creation of federated identity credentials is not supported on user-assigned managed identities in these regions.
How it works
In this security model, the AKS cluster acts as token issuer, Microsoft Entra ID uses OpenID Connect to discover public signing keys and verify the authenticity of the service account token before exchanging it for a Microsoft Entra token. Your workload can exchange a service account token projected to its volume for a Microsoft Entra token using the Azure Identity client library or the Microsoft Authentication Library.
The following table describes the required OIDC issuer endpoints for Microsoft Entra Workload ID:
Endpoint | Description |
---|---|
{IssuerURL}/.well-known/openid-configuration |
Also known as the OIDC discovery document. This contains the metadata about the issuer's configurations. |
{IssuerURL}/openid/v1/jwks |
This contains the public signing key(s) that Microsoft Entra ID uses to verify the authenticity of the service account token. |
The following diagram summarizes the authentication sequence using OpenID Connect.
Webhook Certificate Auto Rotation
Similar to other webhook addons, the certificate is rotated by cluster certificate auto rotation operation.
Service account labels and annotations
Microsoft Entra Workload ID supports the following mappings related to a service account:
- One-to-one where a service account references a Microsoft Entra object.
- Many-to-one where multiple service accounts references the same Microsoft Entra object.
- One-to-many where a service account references multiple Microsoft Entra objects by changing the client ID annotation. For more information, see How to federate multiple identities with a Kubernetes service account.
Note
If the service account annotations are updated, you need to restart the pod for the changes to take effect.
If you've used Microsoft Entra pod-managed identity, think of a service account as an Azure Identity, except a service account is part of the core Kubernetes API, rather than a Custom Resource Definition (CRD). The following describes a list of available labels and annotations that can be used to configure the behavior when exchanging the service account token for a Microsoft Entra access token.
Service account annotations
All annotations are optional. If the annotation isn't specified, the default value will be used.
Annotation | Description | Default |
---|---|---|
azure.workload.identity/client-id |
Represents the Microsoft Entra application client ID to be used with the pod. |
|
azure.workload.identity/tenant-id |
Represents the Azure tenant ID where the Microsoft Entra application is registered. |
AZURE_TENANT_ID environment variable extracted from azure-wi-webhook-config ConfigMap. |
azure.workload.identity/service-account-token-expiration |
Represents the expirationSeconds field for theprojected service account token. It's an optional field that you configure to prevent downtime caused by errors during service account token refresh. Kubernetes service account token expiry isn't correlated with Microsoft Entra tokens. Microsoft Entra tokens expire in 24 hours after they're issued. |
3600 Supported range is 3600-86400. |
Pod labels
Note
For applications using workload identity, it's required to add the label azure.workload.identity/use: "true"
to the pod spec for AKS to move workload identity to a Fail Close scenario to provide a consistent and reliable behavior for pods that need to use workload identity. Otherwise the pods fail after they are restarted.
Label | Description | Recommended value | Required |
---|---|---|---|
azure.workload.identity/use |
This label is required in the pod template spec. Only pods with this label are mutated by the azure-workload-identity mutating admission webhook to inject the Azure specific environment variables and the projected service account token volume. | true | Yes |
Pod annotations
All annotations are optional. If the annotation isn't specified, the default value will be used.
Annotation | Description | Default |
---|---|---|
azure.workload.identity/service-account-token-expiration |
Represents the expirationSeconds field for the projected service account token. It's an optional field that you configure to prevent any downtime caused by errors during service account token refresh. Kubernetes service account token expiry isn't correlated with Microsoft Entra tokens. Microsoft Entra tokens expire in 24 hours after they're issued. 1 |
3600 Supported range is 3600-86400. |
azure.workload.identity/skip-containers |
Represents a semi-colon-separated list of containers to skip adding projected service account token volume. For example, container1;container2 . |
By default, the projected service account token volume is added to all containers if the service account is labeled with azure.workload.identity/use: true . |
azure.workload.identity/inject-proxy-sidecar |
Injects a proxy init container and proxy sidecar into the pod. The proxy sidecar is used to intercept token requests to IMDS and acquire a Microsoft Entra token on behalf of the user with federated identity credential. | true |
azure.workload.identity/proxy-sidecar-port |
Represents the port of the proxy sidecar. | 8000 |
1 Takes precedence if the service account is also annotated.
How to migrate to workload identity
On a cluster that is already running a pod-managed identity, you can configure it to use workload identity one of two ways. The first option allows you to use the same configuration you've implemented for pod-managed identity today. You just need to annotate the service account within the namespace with the identity, and it enables workload identity to inject the annotations into the pods.
The second option is to rewrite your application to use the latest version of the Azure Identity client library.
To help streamline and ease the migration process, we've developed a migration sidecar that converts the IMDS transactions your application makes over to OpenID Connect (OIDC). The migration sidecar isn't intended to be a long-term solution, but a way to get up and running quickly on workload identity. Running the migration sidecar within your application proxies the application IMDS transactions over to OIDC. The alternative approach is to upgrade to a supported version of the Azure Identity client library, which supports OIDC authentication.
The following table summarizes our migration or deployment recommendations for workload identity.
Scenario | Description |
---|---|
New or existing cluster deployment runs a supported version of Azure Identity client library | No migration steps are required. Sample deployment resources: - Deploy and configure workload identity on a new cluster - Tutorial: Use a workload identity with an application on AKS |
New or existing cluster deployment runs an unsupported version of Azure Identity client library | Update container image to use a supported version of the Azure Identity SDK, or use the migration sidecar. |
Next steps
- To learn how to set up your pod to authenticate using a workload identity as a migration option, see Modernize application authentication with workload identity.
- See the tutorial Use a workload identity with an application on Azure Kubernetes Service (AKS), which helps you deploy an Azure Kubernetes Service cluster and configure a sample application to use a workload identity.
Feedback
Submit and view feedback for