Authenticate with a private Docker container registry

To work with container images in an Azure container registry, you log in using the docker login command. You can log in using either an Azure Active Directory service principal or a registry-specific admin account. This article provides more detail about these identities.

Service principal

You can assign a service principal to your registry and use it for basic Docker authentication. Using a service principal is recommended for most scenarios. Provide the app ID and password of the service principal to the docker login command, as shown in the following example:

docker login -u xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx -p myPassword

Once logged in, Docker caches the credentials, so you don't need to remember the app ID.


If you want, you can regenerate the password of a service principal by running the az ad sp reset-credentials command.

Service principals allow role-based access to a registry. Available roles are:

  • Reader (pull only access).
  • Contributor (pull and push).
  • Owner (pull, push, and assign roles to other users).

Anonymous access is not available on Azure Container Registries. For public images you can use Docker Hub.

You can assign multiple service principals to a registry, which allows you to define access for different users or applications. Service principals also enable "headless" connectivity to a registry in developer or DevOps scenarios such as the following examples:

  • Container deployments from a registry to orchestration systems including DC/OS, Docker Swarm and Kubernetes. You can also pull container registries to related Azure services such as Container Service, App Service, Batch, Service Fabric, and others.

  • Continuous integration and deployment solutions (such as Visual Studio Team Services or Jenkins) that build container images and push them to a registry.

Admin account

With each registry you create, an admin account gets created automatically. By default the account is disabled, but you can enable it and manage the credentials, for example through the portal or using the Azure CLI 2.0 commands. Each admin account is provided with two passwords, both of which can be regenerated. The two passwords allow you to maintain connections to the registry by using one password while you regenerate the other password. If the account is enabled, you can pass the user name and either password to the docker login command for basic authentication to the registry. For example:

docker login -u myAdminName -p myPassword1

The admin account is designed for a single user to access the registry, mainly for test purposes. It is not recommended to share the admin account credentials among other users. All users appear as a single user to the registry. Changing or disabling this account disables registry access for all users who use the credentials.

Next steps