How to fix AKS managed identity error in Kubernetes

KubernetesINTERMEDIATEHIGHUpdated Dec 6, 2025· 124 views

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.

Quick fix

Fixes AKS managed identity error

az aks show --resource-group myResourceGroup --name myAKSCluster --query oidcIssuerProfile.enabled
  1. Verify workload identity is enabled on the AKS cluster
  2. Check the OIDC issuer endpoint is accessible
  3. Create or verify federated identity credential
  4. Add workload identity annotations and label to pod
kubernetes — error
az aks show --resource-group myResourceGroup --name myAKSCluster --query oidcIssuerProfile.enabled
AKS managed identity error

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.

Typical symptoms

  • Pod logs show "ManagedIdentityCredential authentication unavailable"
  • Applications fail with 403 Unauthorized when accessing Azure Key Vault, SQL Database, or Storage accounts
  • Pod cannot retrieve tokens: "401 Unauthorized" from IMDS endpoint
  • Error message: "no matching federated identity record found"
  • Pod throws "Identity not found" when querying IMDS
  • OIDC issuer endpoint returns 404 or is unreachable from pod
  • Multiple managed identities attached but pod cannot select correct one

Common causes

  1. Workload identity label missing from pod spec (azure.workload.identity/use: "true")
  2. Federated identity credential issuer URL missing trailing slash or incorrectly formatted
  3. Service account does not have workload identity annotation or federation configured
  4. OIDC issuer endpoint inaccessible or disabled on AKS cluster
  5. Managed identity lacks required RBAC roles or permissions on target resource
  6. Pod security context or network policies blocking access to IMDS endpoint (169.254.169.254:80)
  7. Multiple managed identities attached to VM but client_id not specified
  8. Secret Provider CSI driver using incorrect authentication settings (usePodIdentity or useVMManagedIdentity still enabled)
  9. Cluster control plane OIDC integration not properly enabled during cluster creation
  10. Pod running with old image that does not support workload identity protocol

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"

Advanced notes

The older pod-managed identity (open-source Microsoft Entra pod-managed identity) was deprecated October 24, 2022 and the project archived in September 2023. New clusters should use workload identity exclusively. If migrating from legacy pod-managed identity, you must remove MIC and NMI deployments and reconfigure with federated credentials and service account annotations. For compliance scenarios requiring Fail Close behavior, ensure the label azure.workload.identity/use: "true" is always present on pods needing identity—without it, pods will not receive the projected OIDC token. In CI/CD pipelines (GitHub Actions, Azure Pipelines), workload identity federation can be configured at the GitHub Actions runner or Pipelines service connection level instead of pod level. For debugging, check AKS system pod logs: kubectl logs -n kube-system -l app=azure-workload-identity-webhook. Token file permissions changed in Kubernetes 1.19 from 0600 to 0644, allowing non-root containers to read tokens. Monitor token refresh rates in your application—tokens are short-lived by design and should be obtained fresh before each API call.

Frequently asked questions

What does "AKS managed identity error" mean?
In Azure Kubernetes Service (AKS), managed identities enable pods to authenticate to Azure services without storing credentials in code or Kubernetes secrets. 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.
How do I fix "AKS managed identity error"?
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 causes "AKS managed identity error"?
Workload identity label missing from pod spec (azure.workload.identity/use: "true") Federated identity credential issuer URL missing trailing slash or incorrectly formatted Service account does not have workload identity annotation or federation configured
Is the "AKS managed identity error" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading