Identity bindings for Azure Kubernetes Service (AKS) (Preview)

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:

Context

The existing workload identity feature for AKS has scale limitations because a single user-assigned managed identity (UAMI) can't have more than 20 federated identity credentials (FICs). Large Kubernetes platform deployments might span more than 20 clusters (each cluster has a unique issuer) or have many <namespace, service-account> combinations that require mapping to the same UAMI, exhausting the FIC quota.

Identity binding is an evolution of workload identity on AKS focused on scalability and operational simplicity. For workloads that require Microsoft Entra authentication from AKS, identity bindings are recommended when you need to reuse the same user-assigned managed identity across multiple clusters while staying within the FIC limit.

Conceptual introduction

An identity binding is a resource mapping between one user-assigned managed identity (UAMI) and one AKS cluster that has workloads needing Entra authentication with that identity. If the UAMI MI-1 is needed by workloads running in clusters AKS-1, AKS-2, AKS-3, you create separate identity binding mappings:

  • IB-A mapping MI-1 to AKS-1
  • IB-B mapping MI-1 to AKS-2
  • IB-C mapping MI-1 to AKS-3

Even if the same UAMI is needed across multiple clusters, only one federated identity credential is created per UAMI, addressing the previous 20 FIC limitation. When the cluster operator creates an identity binding, AKS automatically creates (or reuses) the single federated identity credential for that UAMI.

Diagram showing identity bindings mapping a UAMI to multiple AKS clusters while using a single FIC.

After the binding is created and the UAMI is authorized for the cluster, the cluster operator must define ClusterRole and ClusterRoleBinding objects that specify the namespaces and service accounts (granularly or collectively) permitted to use that managed identity for Microsoft Entra token acquisition.

Azure Identity client libraries

To use identity bindings with your application workloads, do the following:

  1. Ensure you're using the minimum required Azure Identity package.
  2. Use WorkloadIdentityCredential and opt into the feature. This feature isn't supported in ManagedIdentityCredential or DefaultAzureCredential.
Language Package Minimum Version How to enable
.NET Azure.Identity v1.18.0-beta.2 or later WorkloadIdentityCredential identity binding mode is disabled by default. Set WorkloadIdentityCredentialOptions.IsAzureKubernetesTokenProxyEnabled to true.
Go azidentity v1.14.0-beta.2 or later Set WorkloadIdentityCredentialOptions.EnableAzureTokenProxy to true.
Java azure-identity v1.19.0-beta.1 or later Call enableAzureTokenProxy() on WorkloadIdentityCredentialBuilder.
JavaScript @azure/identity 4.14.0-beta.1 or later Set enableAzureKubernetesTokenProxy to true in WorkloadIdentityCredentialOptions.
Python azure-identity 1.26.0b1 or later Set use_token_proxy=True in WorkloadIdentityCredential.

FAQ

Is identity sameness (namespace and service account sameness) required across clusters when the same UAMI is used?

No. Identity bindings don't require namespace/service account sameness. It's up to the cluster operator to explicitly authorize the namespaces and service accounts inside each cluster that are allowed to use the managed identity through RBAC.

Can multiple identity bindings be created for the same UAMI?

Yes. The OIDC issuer URL maintained by AKS for that UAMI is the same across all identity bindings referencing the same managed identity.

What permissions are required to create identity bindings?

Required Azure Resource Manager (ARM) permissions:

  • Microsoft.ContainerService/managedClusters/identityBindings/*
  • Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials/*

Note

When an identity binding is created, AKS automatically creates the federated identity credential (FIC) on behalf of the cluster operator. If the caller lacks permission to create FIC resources, the identity binding creation fails.

Required Kubernetes permissions: Ability to create ClusterRole and ClusterRoleBinding objects (cluster admin or equivalent).

What happens to the auto-created FIC after deleting all identity bindings for a UAMI?

There's no automatic garbage collection of the FIC today when the last identity binding referencing a UAMI is deleted. Operators should manually clean up the FIC only after verifying all identity bindings for that UAMI have been removed to avoid disrupting remaining dependencies.

What networking prerequisites exist for identity bindings?

Previously, workload identity required egress to login.partner.microsoftonline.cn so workloads could exchange service account tokens for Microsoft Entra access tokens. With identity bindings, token exchange requests route through a cluster-specific identity binding proxy operated by AKS. Direct egress to login.partner.microsoftonline.cn for token exchange isn't required.

Next steps

Proceed to Set up identity bindings for a step-by-step guide.

  • Last updated on