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

Identity binding is a preview feature for Azure Kubernetes Service (AKS) that extends the existing workload identity feature to address scale limitations around federated identity credentials (FICs) on user-assigned managed identities (UAMIs). With workload identity for AKS, a single UAMI can't have more than 20 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 bindings address this limitation by allowing multiple AKS clusters to share the same UAMI using a single FIC per UAMI. This approach significantly increases scalability and simplifies operations for large-scale AKS environments that require Microsoft Entra authentication.

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:

What is an identity binding?

An identity binding is a resource mapping between one UAMI and one AKS cluster with workloads that need Microsoft Entra authentication with that identity.

Let's say you have a UAMI, MI-1, needed by workloads running in clusters AKS-cluster-1, AKS-cluster-2, and AKS-cluster-3. You can create three identity bindings to map MI-1 to each of these clusters:

  • Identity binding IB-A mapping MI-1 to AKS-cluster-1.
  • Identity binding IB-B mapping MI-1 to AKS-cluster-2.
  • Identity binding IB-C mapping MI-1 to AKS-cluster-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 you create an identity binding, AKS automatically creates (or reuses) the single FIC for that UAMI. The following diagrams illustrate the differences between the previous workload identity model and the new identity bindings model:

Screenshot of two diagrams with one showing identity bindings mapping a UAMI to multiple AKS clusters while using a single FIC and the other showing workload identity mappings.

After you create the identity binding and the UAMI is authorized for the cluster, you 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.

Use identity bindings with Azure Identity client libraries

To use identity bindings with your application workloads, follow these steps:

  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.

The following table outlines the minimum package versions and how to enable identity bindings for each supported language:

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.3 or later Set WorkloadIdentityCredentialOptions.EnableAzureProxy to true.
Java azure-identity v1.19.0-beta.1 or later Call enableAzureTokenProxy() on WorkloadIdentityCredentialBuilder.
JavaScript @azure/identity 4.14.0-beta.2 or later Set enableAzureProxy to true in WorkloadIdentityCredentialOptions.
Python azure-identity 1.26.0b2 or later Set enable_azure_proxy=True in WorkloadIdentityCredential.

Frequently asked questions (FAQs)

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

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 role-based access control (RBAC).

Can I create multiple identity bindings 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 you create an identity binding, AKS automatically creates a FIC. 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.

Related content

  • Last updated on