Authenticate with an Azure container registry

When working with your registry directly, 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 the Azure CLI with az login, and then run the az acr login command:

az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.
az acr login --name <acrName>

When you log in with 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. Once you've logged in this way, your credentials are cached, and subsequent docker commands in your session do not require a username or password.

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

Using az acr login with Azure identities provides Azure role-based access control (Azure RBAC). For some scenarios, you may want to log in to a registry with your own individual identity in Microsoft Entra ID, or configure other Azure users with specific Azure roles and permissions. For cross-service scenarios or to handle the needs of a workgroup or a development workflow where you don't want to manage individual access, you can also log in with a managed identity for Azure resources.

az acr login with --expose-token

In some cases, you need to authenticate with 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 local Shell, which provides the Docker CLI but doesn't run the Docker daemon.

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

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

Output displays the access token, abbreviated here:

{
  "accessToken": "<Your_Access_Toke_Placeholder>",
  "loginServer": "myregistry.azurecr.cn"
}

For registry authentication, we recommend that you 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 password:

docker login myregistry.azurecr.cn --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.cn \
            --username 00000000-0000-0000-0000-000000000000 \
            --password-stdin

When working with your registry directly, 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 with Connect-AzAccount -Environment AzureChinaCloud, and then run the Connect-AzContainerRegistry cmdlet:

Connect-AzAccount -Environment AzureChinaCloud
Connect-AzContainerRegistry -Name <acrName>

When you log in with Connect-AzContainerRegistry, PowerShell uses the token created when you executed Connect-AzAccount -Environment AzureChinaCloud 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. Once you've logged in this way, your credentials are cached, and subsequent docker commands in your session do not require a username or password.

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

Using Connect-AzContainerRegistry with Azure identities provides Azure role-based access control (Azure RBAC). For some scenarios, you may want to log in to a registry with your own individual identity in Microsoft Entra ID, or configure other Azure users with specific Azure roles and permissions. For cross-service scenarios or to handle the needs of a workgroup or a development workflow where you don't want to manage individual access, you can also log in with a managed identity for Azure resources.

To enable the admin user for an existing registry, you can 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, you can use the EnableAdminUser parameter of the Update-AzContainerRegistry command in Azure PowerShell:

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