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 (that is, a service account), to enable pods to use a Kubernetes identity. 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 or the Microsoft Authentication Library (MSAL) collection, together with application registration. Your workload can use any of these libraries to seamlessly authenticate and access Azure cloud resources.

This article helps you to understand Microsoft Entra Workload ID, and reviews the options available to plan your project strategy and potential migration from Microsoft Entra pod-managed identity.

Note

You can use Service Connector to help you configure some steps automatically. See also: What is Service Connector?

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 run az 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 the WorkloadIdentityCredential.
  • Create a ChainedTokenCredential instance that includes WorkloadIdentityCredential.
  • 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 have a maximum of 20 federated identity credentials per managed identity.
  • It takes a few seconds for the federated identity credential to be propagated after being initially added.
  • The 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 the 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 (MSAL).

Diagram of the AKS workload identity security model.

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.

Diagram of the AKS workload identity OIDC authentication sequence.

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 reference 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 must 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 security principal, except that a service account is part of the core Kubernetes API, rather than a Custom Resource Definition (CRD). The following sections describe 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 the
projected 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 Microsoft Entra Workload ID

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 that you've implemented for pod-managed identity. You can annotate the service account within the namespace with the identity to enable Microsoft Entra Workload ID and 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
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