Use Azure AD workload identity (preview) with Azure Kubernetes Service (AKS)

Today with Azure Kubernetes Service (AKS), you can assign managed identities at the pod-level, which has been a preview feature. This pod-managed identity allows the hosted workload or application access to resources through Azure Active Directory (Azure AD). For example, a workload stores files in Azure Storage, and when it needs to access those files, the pod authenticates itself against the resource as an Azure managed identity. This authentication method has been replaced with Azure Active Directory (Azure AD) workload identities (preview), which integrate with the Kubernetes native capabilities to federate with any external identity providers. This approach is simpler to use and deploy, and overcomes several limitations in Azure AD pod-managed identity:

  • Removes the scale and performance issues that existed for identity assignment
  • Supports Kubernetes clusters hosted in any cloud or on-premises
  • Supports both Linux and Windows workloads
  • Removes the need for Custom Resource Definitions and pods that intercept Azure Instance Metadata Service (IMDS) traffic
  • Avoids the complicated and error-prone installation steps such as cluster role assignment from the previous iteration

Azure AD workload identity works especially well with the Azure Identity client library using the Azure SDK and the Microsoft Authentication Library (MSAL) 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 migration phases and project strategy.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. For more information, see the following support articles:

Dependencies

  • AKS supports Azure AD workload identities on version 1.22 and higher.

  • The Azure CLI version 2.40.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.

  • The aks-preview extension version 0.5.102 or later.

  • The following are the minimum versions of the Azure Identity client library supported:

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.

How it works

In this security model, the AKS cluster acts as token issuer, Azure Active Directory uses OpenID Connect to discover public signing keys and verify the authenticity of the service account token before exchanging it for an Azure AD token. Your workload can exchange a service account token projected to its volume for an Azure AD token using the Azure Identity client library or the Microsoft Authentication Library.

Diagram of the AKS workload identity security model.

The following table describes the required OIDC issuer endpoints for Azure AD workload identity:

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 Azure AD 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.

Service account labels and annotations

Azure AD workload identity supports the following mappings related to a service account:

  • One-to-one where a service account references an Azure AD object.
  • Many-to-one where multiple service accounts references the same Azure AD object.
  • One-to-many where a service account references multiple Azure AD objects by changing the client ID annotation.

Note

If the service account annotations are updated, you need to restart the pod for the changes to take effect.

If you've used Azure AD 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 an Azure AD access token.

Service account labels

Label Description Recommended value Required
azure.workload.identity/use Represents the service account
is to be used for workload identity.
true Yes

Service account annotations

Annotation Description Default
azure.workload.identity/client-id Represents the Azure AD application
client ID to be used with the pod.
azure.workload.identity/tenant-id Represents the Azure tenant ID where the
Azure AD 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 Azure AD tokens. Azure AD tokens expire in 24 hours after they're issued.
3600
Supported range is 3600-86400.

Pod labels

Note

For applications using Workload Identity it is now required to add the label 'azure.workload.identity/use: "true"' pod label in order for AKS to move Workload Identity to a "Fail Close" scenario before GA to provide a consistent and reliable behavior for pods that need to use workload identity.

Label Description Recommended value Required
azure.workload.identity/use Represents the pod is to be used for workload identity. true Yes

Pod annotations

Annotation Description Default
azure.workload.identity/use Represents the service account
is to be used for workload identity.
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 Azure AD tokens. Azure AD 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 an Azure AD token on behalf of the user with federated identity credential. true
azure.workload.identity/proxy-sidecar-port Represents the port of the proxy sidecar. 8080

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