🚨 Azure Error Guide: 'unauthorized: authentication required' — Fix ACR Pull Auth

Overview

Azure Container Registry (ACR) rejects a pull or push when the caller has no valid credential for the registry. Docker and containerd surface it as:

Error response from daemon: Head "https://myregistry.azurecr.io/v2/app/manifests/latest":
unauthorized: authentication required, visit https://aka.ms/acr/authorization for more information.

In AKS the same failure appears on the pod as an ImagePullBackOff whose underlying event is:

Failed to pull image "myregistry.azurecr.io/app:latest": failed to resolve reference
"myregistry.azurecr.io/app:latest": failed to authorize: failed to fetch anonymous token:
unexpected status from GET request ... 401 Unauthorized

Symptoms

• docker pull/docker push to *.azurecr.io fails with unauthorized: authentication required.
• az acr login succeeds but a later pull still fails (token expired between the two).
• AKS pods stay in ImagePullBackOff/ErrImagePull with a 401 in kubectl describe pod events.
• CI pipelines that pushed yesterday fail today with 401 after the ACR token or service principal secret rotated.
• Anonymous pull works for some public images but private repositories return 401.

Common Root Causes

• Not logged in / expired token. az acr login issues a short-lived token (~3 hours). Docker’s cached credential expires and later pulls fail.
• AKS not attached to ACR. The cluster’s kubelet identity has no AcrPull role on the registry, so pods cannot pull private images.
• Missing AcrPull role. The service principal, managed identity, or user lacks the AcrPull (or AcrPush) role assignment on the registry scope.
• Wrong identity in CI. The pipeline authenticates as an identity without registry access, or a rotated service principal secret is stale.
• Admin user disabled but credentials expected. Scripts using the registry admin username/password fail because the admin account is disabled (the secure default).
• Docker credential cache stale. An old entry in ~/.docker/config.json shadows a fresh login.

Diagnostic Workflow

All commands below are read-only (except az acr login, which only refreshes a token). Confirm the registry exists and your access:

# Confirm the registry name/login server and that you can see it.
az acr show --name <registry> --query "{loginServer:loginServer, adminEnabled:adminUserEnabled}" --output table

# Test authentication and repository access with your current identity.
az acr login --name <registry>
az acr repository list --name <registry> --output table

For AKS, verify the cluster is attached and which identity pulls images:

# The kubelet (agentpool) identity is what pulls images; get its objectId.
az aks show -g <rg> -n <cluster> --query "identityProfile.kubeletidentity.clientId" --output tsv

# Does that identity have AcrPull on the registry?
az role assignment list --scope $(az acr show -n <registry> --query id -o tsv) \
  --query "[?roleDefinitionName=='AcrPull'].{principal:principalId, role:roleDefinitionName}" --output table

Inspect the failing pod event in AKS:

kubectl describe pod <pod> | grep -A5 -i 'failed to pull\|unauthorized\|imagepull'

Example Root Cause Analysis

After a working proof-of-concept, a team’s AKS deployment stalled with every pod in ImagePullBackOff. kubectl describe pod showed a 401 pulling from myregistry.azurecr.io. Developers could az acr login and docker pull the same image from their laptops, which pointed at the cluster’s identity, not the image or registry.

az aks show --query identityProfile.kubeletidentity.clientId returned the kubelet managed identity. Listing role assignments on the registry scope showed no AcrPull for that principal — the cluster had never been attached to the registry. The developers’ pulls worked because their user accounts had access; the cluster’s identity did not.

The fix was az aks update -g <rg> -n <cluster> --attach-acr <registry>, which grants the kubelet identity AcrPull on the registry. Pods pulled successfully on the next retry. Root cause: the AKS kubelet identity lacked the AcrPull role, unrelated to any user-side credential.

Prevention Best Practices

• Attach ACR to AKS with az aks update --attach-acr so the kubelet identity always has AcrPull; avoid image pull secrets where managed identity works.
• Use managed identity or OIDC in CI, not long-lived admin credentials, and assign the minimal AcrPull/AcrPush role at the registry scope.
• Keep the admin account disabled and rely on Entra-based tokens; only enable admin for narrow break-glass cases.
• Re-login before long jobs, since az acr login tokens are short-lived; do not cache tokens across pipeline stages.
• Grant least privilege at registry scope rather than broad subscription roles, and audit role assignments periodically.
• Clear stale Docker credentials (docker logout <loginServer>) when switching identities to avoid a cached 401.

Quick Command Reference

# Confirm registry and admin state.
az acr show -n <registry> --query "{loginServer:loginServer, adminEnabled:adminUserEnabled}"

# Refresh auth and test access.
az acr login -n <registry>
az acr repository list -n <registry> -o table

# Attach ACR to an AKS cluster (grants AcrPull to kubelet identity).
az aks update -g <rg> -n <cluster> --attach-acr <registry>

# Check AcrPull assignments on the registry.
az role assignment list --scope $(az acr show -n <registry> --query id -o tsv) -o table

# Inspect an ImagePullBackOff in AKS.
kubectl describe pod <pod>

Conclusion

unauthorized: authentication required from ACR is always a credential problem, not an image problem: the caller has no valid token or role for the registry. For interactive use, refresh with az acr login; for AKS, attach the registry so the kubelet identity gets AcrPull; for CI, authenticate with managed identity/OIDC and assign the minimal role at registry scope. Keeping the admin account off and using Entra-based, least-privilege access makes these 401s rare and easy to reason about.