Authenticate with Azure Container Registry

You can authenticate with an Azure container registry in several ways. Review these options to determine what works best for your container registry usage scenario.

For most scenarios, authenticate by using one of the following Microsoft Entra ID-based methods:

Individual login - Authenticate directly to a registry
Service principal - Use a Microsoft Entra service principal for unattended, or "headless," authentication by applications and container orchestrators

Authentication options

The following table lists available authentication methods and typical scenarios, with links to more details.

Tip

For authentication from Azure Kubernetes Service (AKS) or another Kubernetes cluster, see Scenarios to authenticate with Azure Container Registry from Kubernetes.

Method	How to authenticate	Scenarios	Microsoft Entra role-based access control (RBAC)	Limitations
Individual Microsoft Entra identity	`az acr login` in Azure CLI `Connect-AzContainerRegistry` in Azure PowerShell	Interactive push/pull by developers, testers	Yes	Microsoft Entra token must be renewed every 3 hours
Microsoft Entra service principal	`docker login` `az acr login` in Azure CLI `Connect-AzContainerRegistry` in Azure PowerShell Registry login settings in APIs or tooling	Unattended push from CI/CD pipeline Unattended pull to Azure or external services	Yes	SP password default expiry is 1 year
Microsoft Entra managed identity for Azure resources	`docker login`  `az acr login` in Azure CLI `Connect-AzContainerRegistry` in Azure PowerShell	Unattended push from Azure CI/CD pipeline Unattended pull to Azure services For a list of managed identity role assignment scenarios, see ACR Entra permissions and role assignments.	Yes	Can only be used from select Azure services that support managed identities for Azure resources
Admin user	`docker login`	Interactive push/pull by individual developer or tester Portal deployment of image from registry to Azure App Service or Azure Container Instances	No, always pull and push access	High level of access. Single account per registry; not recommended for multiple users
Non-Microsoft Entra token-based repository permissions	`docker login` `az acr login` in Azure CLI `Connect-AzContainerRegistry` in Azure PowerShell	Interactive push/pull to repository by individual developer or tester Unattended pull from repository by individual system or external device	Token-based repository permissions does not support Microsoft Entra RBAC role assignments. For Microsoft Entra-based repository permissions, see Azure attribute-based access control (ABAC) repository permissions in Azure Container Registry instead.	Not currently integrated with Microsoft Entra ID

Authenticate with Microsoft Entra ID

When working with your registry directly, such as pulling images and pushing images from a development workstation to a registry you created, authenticate by using your individual Azure identity.

Azure CLI
Azure PowerShell

az login
az acr login --name <acrName>

When you sign in by using az acr login, the CLI uses the token created when you executed az login to seamlessly authenticate your session with your registry. To complete the authentication flow, the Docker CLI and Docker daemon must be installed and running in your environment. az acr login uses the Docker client to set a Microsoft Entra token in the docker.config file. After you sign in this way, your credentials are cached, and subsequent docker commands in your session don't require a username or password.

Tip

Also use az acr login to authenticate an individual identity when you want to push or pull artifacts other than Docker images to your registry, such as OCI artifacts.

For registry access, the token that az acr login uses is valid for 3 hours, so always sign in to the registry before running a docker command. If your token expires, refresh it by using the az acr login command again to reauthenticate.

Using az acr login with Azure identities enables Azure role-based access control (RBAC). For some scenarios, you might want to sign in to a registry with your own individual identity in Microsoft Entra ID, or configure other Azure users with specific roles. For cross-service scenarios, or for a workgroup or a development workflow where you don't want to manage individual access, you can also sign in by using a managed identity for Azure resources.

In some cases, you need to authenticate by using az acr login when the Docker daemon isn't running in your environment. For example, you might need to run az acr login in a script in Azure Cloud Shell, which provides the Docker CLI but doesn't run the Docker daemon.

For this scenario, run az acr login with the --expose-token parameter. This option returns an access token instead of signing in through the Docker CLI.

az acr login --name <acrName> --expose-token

The output displays the access token, abbreviated here:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs[...]24V7wA",
  "loginServer": "myregistry.azurecr.io"
}

For registry authentication, store the token credential in a safe location and follow recommended practices to manage docker login credentials. For example, store the token value in an environment variable:

TOKEN=$(az acr login --name <acrName> --expose-token --output tsv --query accessToken)

Then, run docker login, passing 00000000-0000-0000-0000-000000000000 as the username and using the access token as the password:

docker login myregistry.azurecr.io --username 00000000-0000-0000-0000-000000000000 --password-stdin <<< $TOKEN

Likewise, you can use the token returned by az acr login with the helm registry login command to authenticate with the registry:

echo $TOKEN | helm registry login myregistry.azurecr.io \
            --username 00000000-0000-0000-0000-000000000000 \
            --password-stdin

When you work directly with your registry, such as pulling images to and pushing images from a development workstation to a registry you created, authenticate by using your individual Azure identity. Sign in to Azure PowerShell by using Connect-AzAccount, and then run the Connect-AzContainerRegistry cmdlet:

Connect-AzAccount
Connect-AzContainerRegistry -Name <acrName>

When you sign in by using Connect-AzContainerRegistry, PowerShell uses the token created when you executed Connect-AzAccount to seamlessly authenticate your session with your registry. To complete the authentication flow, the Docker CLI and Docker daemon must be installed and running in your environment. Connect-AzContainerRegistry uses the Docker client to set a Microsoft Entra token in the docker.config file. After you sign in this way, your credentials are cached, and subsequent docker commands in your session don't require a username or password.

Tip

Also use Connect-AzContainerRegistry to authenticate an individual identity when you want to push or pull artifacts other than Docker images to your registry, such as OCI artifacts.

For registry access, the token used by Connect-AzContainerRegistry is valid for 3 hours, so always log in to the registry before running a docker command. If your token expires, refresh it by using the Connect-AzContainerRegistry command again to reauthenticate.

Using Connect-AzContainerRegistry with Azure identities enables Azure role-based access control (RBAC). For some scenarios, you might want to sign in to a registry with your own individual identity in Microsoft Entra ID, or configure other Azure users with specific roles. For cross-service scenarios, or for a workgroup or a development workflow where you don't want to manage individual access, you can also sign in by using a managed identity for Azure resources.

Service principal

If you assign a service principal to your registry, your application or service can use it for headless authentication. Service principals enable Azure role-based access control (RBAC) in a registry. You can assign multiple service principals to a registry, so you can use different supported roles for specific applications.

For more information, see Azure Container Registry authentication with service principals.

Admin account

Each container registry includes an admin user account, which is disabled by default. You can enable the admin user and manage its credentials in the Azure portal, or by using the Azure CLI, Azure PowerShell, or other Azure tools. The admin account has full permissions to the registry, so you should enable it only when necessary.

The admin account is currently required for some scenarios to deploy an image from a container registry to certain Azure services. For example, the admin account is needed when you use the Azure portal to deploy a container image from a registry directly to Azure Container Instances or Azure Web Apps for Containers.

Important

The admin account is designed for a single user to access the registry, mainly for testing purposes. Don't share the admin account credentials among multiple users. All users authenticating with the admin account appear as a single user with push and pull access to the registry. Changing or disabling this account disables registry access for all users who use its credentials. Use individual identity for users and service principals for headless scenarios.

The admin account has two passwords, both of which you can regenerate. Regenerating passwords for admin accounts takes approximately 60 seconds to replicate and become available. Because the account has two passwords, you can maintain connection to the registry by using one password while you regenerate the other. If you enable the admin account, you can pass the username and either password to the docker login command when prompted for basic authentication to the registry. For recommended practices to manage authentication credentials, see the docker login command reference.

Azure CLI
Azure PowerShell

To enable the admin user for an existing registry, use the --admin-enabled parameter of the az acr update command in the Azure CLI:

az acr update -n <acrName> --admin-enabled true

To enable the admin user for an existing registry, use the EnableAdminUser parameter of the Update-AzContainerRegistry command in Azure PowerShell:

Update-AzContainerRegistry -Name <acrName> -ResourceGroupName myResourceGroup -EnableAdminUser

You can also enable the admin user for your registry in the Azure portal. In the service menu, under Settings, select Access keys. Then check the Admin user box to enable the account. The admin username is displayed, along with the two passwords, which you can show or regenerate as needed.

In some scenarios, you need to use alternative container tools like podman instead of Docker.

The default container tool is set to docker for az acr login commands. If you don't set the default container tool and the docker command is missing in your environment, you see an error. To change the default container tool that the az acr login command uses, set the environment variable DOCKER_COMMAND. For example:

DOCKER_COMMAND=podman \
az acr login --name <acrName>

Next steps

Feedback

Was this page helpful?

Last updated on 2026-02-03

Share via