How to fix AKS managed identity error in Kubernetes

KubernetesINTERMEDIATEHIGH

AKS managed identity errors occur when pods fail to authenticate to Azure services because the managed identity is not properly configured, accessible, or lacks required RBAC permissions. These errors prevent your applications from accessing Azure resources like Key Vault, databases, and storage.

What this error means

In Azure Kubernetes Service (AKS), managed identities enable pods to authenticate to Azure services without storing credentials in code or Kubernetes secrets. When an AKS managed identity error occurs, it means the pod cannot obtain a token from the Azure Instance Metadata Service (IMDS) endpoint at 169.254.169.254. This happens when the identity is misconfigured, the Node Managed Identity (NMI) pods are not intercepting requests correctly, or the identity lacks permission to access the target Azure resource. AKS supports two managed identity approaches: the legacy pod-managed identity (deprecated as of October 2022) and the modern workload identity, which uses OIDC federation with Kubernetes service accounts. Most AKS clusters now use workload identity for better security and native Kubernetes integration.

How to fix "AKS managed identity error"

1Verify workload identity is enabled on the AKS cluster

Check if your cluster has workload identity enabled:

bash

az aks show --resource-group myResourceGroup --name myAKSCluster --query oidcIssuerProfile.enabled

If output is false or null, enable it:

bash

az aks update --resource-group myResourceGroup --name myAKSCluster --enable-oidc-issuer

After enabling, update the OIDC issuer URL in your Kubernetes configurations if you have existing ones.

2Check the OIDC issuer endpoint is accessible

Get the OIDC issuer URL from your cluster:

bash

az aks show --resource-group myResourceGroup --name myAKSCluster --query oidcIssuerProfile.issuerUrl --output tsv

Example output: https://oidc.prod-aks.azure.com/12345678-1234-1234-1234-123456789012/

From a pod, verify you can reach this endpoint:

bash

kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- curl https://oidc.prod-aks.azure.com/12345678-1234-1234-1234-123456789012/.well-known/openid-configuration

If the request fails, the cluster network is blocking access. Check network policies and firewall rules.

3Create or verify federated identity credential

Create a federated identity credential linking your Kubernetes service account to a managed identity:

bash

az identity federated-credential create \
  --resource-group myResourceGroup \
  --identity-name myManagedIdentity \
  --name myFederatedCred \
  --issuer https://oidc.prod-aks.azure.com/12345678-1234-1234-1234-123456789012/ \
  --subject system:serviceaccount:default:myServiceAccount

Critical: The issuer URL must have a trailing slash and match exactly (check for typos, special characters, or missing path).

Verify the credential was created:

bash

az identity federated-credential show \
  --resource-group myResourceGroup \
  --identity-name myManagedIdentity \
  --name myFederatedCred

4Add workload identity annotations and label to pod

Update your pod YAML to include the workload identity configuration:

yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: myServiceAccount
  namespace: default
  annotations:
    azure.workload.identity/client-id: "12345678-1234-1234-1234-123456789abc"
---
apiVersion: v1
kind: Pod
metadata:
  name: myapp
  namespace: default
spec:
  serviceAccountName: myServiceAccount
  labels:
    azure.workload.identity/use: "true"  # Critical label
  containers:
  - name: app
    image: myapp:latest
    env:
    - name: AZURE_CLIENT_ID
      value: "12345678-1234-1234-1234-123456789abc"
    - name: AZURE_TENANT_ID
      value: "12345678-1234-1234-1234-123456789def"
    - name: AZURE_AUTHORITY_HOST
      value: "https://login.microsoftonline.com"

The label azure.workload.identity/use: "true" tells AKS to enable workload identity for this pod.

5Verify managed identity has required RBAC permissions

The managed identity must have appropriate roles on the resource it needs to access. For example, accessing Key Vault:

bash

az keyvault set-policy --name myKeyVault \
  --object-id $(az identity show --resource-group myResourceGroup --name myManagedIdentity --query principalId -o tsv) \
  --secret-permissions get list \
  --key-permissions get list

For other resources:
- Storage Account: Assign "Storage Blob Data Reader" role
- SQL Database: Ensure managed identity is added as database user with appropriate permissions
- Container Registry: Assign "AcrPull" role

Check current role assignments:

bash

az role assignment list --scope /subscriptions/mySubscription/resourceGroups/myResourceGroup \
  --assignee-object-id $(az identity show --resource-group myResourceGroup --name myManagedIdentity --query principalId -o tsv)

6Ensure pod can reach the IMDS endpoint

By default, pods reach IMDS at 169.254.169.254:80. Verify network connectivity:

bash

kubectl run -it --rm debug --image=busybox --restart=Never -- wget -O- http://169.254.169.254/metadata/identity/oauth2/token?api-version=2017-09-01

If this times out or fails:
- Check pod network policies: kubectl get networkpolicies -A
- Verify node can reach IMDS: SSH to node and run the same wget command
- For custom CNI plugins, ensure they do not block link-local traffic to 169.254.169.254

If using Azure Firewall or restrictive NSGs, allow outbound traffic to the IMDS endpoint.

7Configure application SDK for workload identity

Update your application code to use Azure SDKs with workload identity. Most Azure SDKs (Python, .NET, Node.js, Go) support the DefaultAzureCredential pattern:

Python (azure-identity package):

python

from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://myvault.vault.azure.net/", credential=credential)

Node.js:

javascript

const { DefaultAzureCredential } = require("@azure/identity");
const { SecretClient } = require("@azure/keyvault-secrets");

const credential = new DefaultAzureCredential();
const client = new SecretClient("https://myvault.vault.azure.net/", credential);

The DefaultAzureCredential automatically detects the workload identity environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_AUTHORITY_HOST) and uses them to authenticate.

8If using Secret Provider CSI driver, update SecretProviderClass

If using the Azure Secrets Store CSI Driver, ensure it is configured for workload identity (not legacy pod-managed identity):

yaml

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: azure-secrets
spec:
  provider: azure
  parameters:
    usePodIdentity: "false"        # Disable legacy pod-managed identity
    useVMManagedIdentity: "false"  # Disable VM-based identity
    clientID: "12345678-1234-1234-1234-123456789abc"  # Workload identity client ID
    keyvaultName: myVault
    objects: |
      array:
        - |
          objectName: mySecret
          objectType: secret
          objectVersion: ""
    tenantID: "12345678-1234-1234-1234-123456789def"

Then reference in your pod spec:

yaml

volumes:
- name: secrets-store
  csi:
    driver: secrets-store.csi.k8s.io
    readOnly: true
    volumeAttributes:
      secretProviderClass: "azure-secrets"

How to fix AKS managed identity error in Kubernetes

What this error means

Typical symptoms

Common causes

How to fix "AKS managed identity error"

Advanced notes

Related errors

Official resources & further reading