Authenticate with an Azure container registry
There are several ways to authenticate with an Azure container registry, each of which is applicable to one or more registry usage scenarios.
Recommended ways include authenticating to a registry directly via individual login, or your applications and container orchestrators can perform unattended, or "headless," authentication by using an Azure Active Directory (Azure AD) service principal.
The following table lists available authentication methods and recommended scenarios. See linked content for details.
|Method||How to authenticate||Scenarios||RBAC||Limitations|
|Individual AD identity||
||Interactive push/pull by developers, testers||Yes||AD token must be renewed every 3 hours|
|AD service principal||
Registry login settings in APIs or tooling
Kubernetes pull secret
|Unattended push from CI/CD pipeline
Unattended pull to Azure or external services
|Yes||SP password default expiry is 1 year|
|Integrate with AKS||Attach registry when AKS cluster created or updated||Unattended pull to AKS cluster||No, pull access only||Only available with AKS cluster|
|Managed identity for Azure resources||
||Unattended push from Azure CI/CD pipeline
Unattended pull to Azure services
|Yes||Use only from Azure services that support managed identities for Azure resources|
||Interactive push/pull by individual developer or tester||No, always pull and push access||Single account per registry, not recommended for multiple users|
|Repository-scoped access token||
||Interactive push/pull to repository by individual developer or tester
Unattended push/pull to repository by individual system or external device
|Yes||Not currently integrated with AD identity|
Individual login with Azure AD
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, Docker must be installed and running in your environment.
az acr login uses the Docker client to set an Azure Active Directory 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.
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 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.
az acr login with Azure identities provides role-based access. For some scenarios, you may want to log in to a registry with your own individual identity in Azure AD. 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.
If you assign a service principal to your registry, your application or service can use it for headless authentication. Service principals allow role-based access to a registry, and you can assign multiple service principals to a registry. Multiple service principals allow you to define different access for different applications.
The available roles for a container registry include:
AcrPush: pull and push
Owner: pull, push, and assign roles to other users
For a complete list of roles, see Azure Container Registry roles and permissions.
For CLI scripts to create a service principal for authenticating with an Azure container registry, and more guidance, see Azure Container Registry authentication with service principals.
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 or other Azure tools.
The admin account is designed for a single user to access the registry, mainly for testing purposes. We do not recommend sharing 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. Individual identity is recommended for users and service principals for headless scenarios.
The admin account is provided with two passwords, both of which can be regenerated. Two passwords allow you to maintain connection to the registry by using one password while you regenerate the other. If the admin account is enabled, you can pass the username and either password to the
docker login command when prompted for basic authentication to the registry. For example:
docker login myregistry.azurecr.io
For best practices to manage login credentials, see the docker login command reference.
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
You can enable the admin user in the Azure portal by navigating your registry, selecting Access keys under SETTINGS, then Enable under Admin user.