/identity-managed-identity

AKS Microsoft Entra Workload ID

For new AKS workloads, use Microsoft Entra Workload ID. Do not use the deprecated Microsoft Entra pod-managed identity for new workloads.

Required components

1. AKS OIDC issuer enabled.
2. User-assigned managed identity for the workload.
3. Federated identity credential on the managed identity.
4. Kubernetes service account annotated with the managed identity client ID.
5. Pod uses the annotated service account.
6. Azure SDK uses WorkloadIdentityCredential or a constrained credential chain that includes workload identity.

Federated credential

oidc_issuer=$(az aks show \
  --resource-group "$aks_resource_group" \
  --name "$aks_name" \
  --query "oidcIssuerProfile.issuerUrl" -o tsv)

az identity federated-credential create \
  --name "fic-${namespace}-${service_account_name}" \
  --identity-name "$identity_name" \
  --resource-group "$identity_resource_group" \
  --issuer "$oidc_issuer" \
  --subject "system:serviceaccount:${namespace}:${service_account_name}" \
  --audiences "api://AzureADTokenExchange"

Kubernetes service account

apiVersion: v1
kind: ServiceAccount
metadata:
  name: api
  namespace: production
  annotations:
    azure.workload.identity/client-id: "<managed-identity-client-id>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: production
spec:
  template:
    metadata:
      labels:
        azure.workload.identity/use: "true"
    spec:
      serviceAccountName: api
      containers:
        - name: api
          image: <image>

Bicep federated credential shape

resource identity 'Microsoft.ManagedIdentity/userAssignedIdentities@2024-11-30' existing = {
  name: identity_name
}

resource federated_credential 'Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials@2024-11-30' = {
  name: 'fic-${namespace}-${service_account_name}'
  parent: identity
  properties: {
    issuer: oidc_issuer_url
    subject: 'system:serviceaccount:${namespace}:${service_account_name}'
    audiences: [
      'api://AzureADTokenExchange'
    ]
  }
}

Code

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

var credential = new WorkloadIdentityCredential();
var client = new SecretClient(new Uri("https://<vault>.vault.azure.net"), credential);

Setup ordering (silent-failure trap)

Workload Identity token injection happens at pod admission via a mutating webhook. The order of operations matters, getting it wrong produces pods with no AZURE_CLIENT_ID / AZURE_FEDERATED_TOKEN_FILE env vars and they silently fall back to the kubelet identity (or fail with 403). Correct sequence:

1. Enable OIDC issuer on the cluster (--enable-oidc-issuer).
2. Enable Workload Identity on the cluster (--enable-workload-identity).
3. Create the federated identity credential with subject system:serviceaccount:<ns>:<sa> matching the EXACT namespace + service-account name.
4. Annotate the ServiceAccount (azure.workload.identity/client-id) AND add the pod template label (azure.workload.identity/use: "true").
5. Only then start or restart the pods, the webhook injects the projected token volume and env vars at admission.

If pods are already running before step 4, they will NOT pick up the annotation retroactively. You must restart them (kubectl rollout restart deployment/<d> -n <ns>). This is the most common silent failure when retrofitting Workload Identity onto an already-deployed workload, including operator-installed platforms like Drasi.

Common failures