Use a managed identity to authenticate to an Azure container registry

You can use a managed identity for Azure resources to authenticate to an Azure container registry from another Azure resource, without needing to provide or manage registry credentials.

For example, set up a user-assigned or system-assigned managed identity on a Linux VM to access container images from your container registry, as easily as you use a public registry. Or, set up an Azure Kubernetes Service cluster to use its managed identity to pull container images from Azure Container Registry for pod deployments.

For an overview of managed identities in Azure, see What is managed identities for Azure resources?

You can assign a managed identity a role with pull only, push and pull, or other permissions to one or more private registries in Azure. For a complete list of registry roles, see Azure Container Registry permissions and roles overview.

Then, use the identity to authenticate to any service that supports managed identities, without requiring any credentials in your code.

In this article, you learn how to:

Enable a user-assigned or system-assigned identity on an Azure virtual machine (VM)
Grant the identity access to an Azure container registry
Use the managed identity to access the registry and pull a container image

Prerequisites

You can use either Azure CLI or Azure PowerShell to complete the steps in this article. Use the most recent version of either tool. If you don't have either tool installed, see Install the Azure CLI or Install Azure PowerShell.

To set up a container registry and push a container image to it, you must also have Docker installed locally. Docker provides packages that easily configure Docker on any macOS, Windows, or Linux system.

If you don't already have an Azure container registry, create a registry and push a sample container image to it. Follow the steps to create a registry by using the Azure CLI, Azure PowerShell, or the Azure portal.

This article assumes you have the aci-helloworld:v1 container image stored in your registry. The examples use a registry name of myContainerRegistry. You can replace these values with your own registry and image names.

Create and configure a Docker-enabled VM

Create a Docker-enabled Ubuntu VM to use with your managed identity. You also need to install either the Azure CLI or Azure PowerShell on the virtual machine, depending on which tool you want to use.

If you already have an Azure VM with Azure CLI or Azure PowerShell installed, you can move to the next section.

Deploy a default Ubuntu Azure virtual machine by using az vm create. The following example creates a VM named myDockerVM in an existing resource group named myResourceGroup:

az vm create \
    --resource-group myResourceGroup \
    --name myDockerVM \
    --image Ubuntu2204 \
    --admin-username azureuser \
    --generate-ssh-keys

It takes a few minutes to create the VM. When the command finishes, note the publicIpAddress displayed by the Azure CLI. Use this address to make SSH connections to the VM in the next step.

Deploy a default Ubuntu Azure virtual machine by using New-AzVM. The following example creates a VM named myDockerVM in an existing resource group named myResourceGroup. You're prompted for a user name that you use when you connect to the VM. Specify azureuser as the user name. You're also asked for a password, which you can leave blank. Password authentication for the VM is disabled when using an SSH key.

$vmParams = @{
    ResourceGroupName   = 'MyResourceGroup'
    Name                = 'myDockerVM'
    Image               = 'UbuntuLTS'
    PublicIpAddressName = 'myPublicIP'
    GenerateSshKey      = $true
    SshKeyName          = 'mySSHKey'
}
New-AzVM @vmParams

It takes a few minutes to create the VM. When the command finishes, run the following command to get the public IP address. Use this address to make SSH connections to the VM in the next step.

Get-AzPublicIpAddress -Name myPublicIP -ResourceGroupName myResourceGroup | Select-Object -ExpandProperty IpAddress

Install Docker on the VM

Next, install Docker on your VM so that it can pull and run container images from your Azure Container Registry.

Once the VM is running, make an SSH connection to the VM. Replace publicIpAddress with the public IP address of your VM.

ssh azureuser@publicIpAddress

Run the following command to install Docker on the VM:

sudo apt update
sudo apt install docker.io -y

After installation, run the following command to verify that Docker is running properly on the VM:

sudo docker run -it mcr.microsoft.com/hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.
[...]

Install Azure CLI or Azure PowerShell on the VM

Azure CLI
Azure PowerShell

Follow the steps in Install Azure CLI with apt to install the Azure CLI on your Ubuntu virtual machine. For this article, be sure to install the most recent version.

After installing the Azure CLI, exit the SSH session.

Follow the steps in Installing PowerShell on Ubuntu and Install the Azure Az PowerShell module to install PowerShell and Azure PowerShell on your Ubuntu virtual machine. For this article, be sure to install Azure PowerShell version 7.5.0 or later.

Depending on your VM's setup, you might need to use sudo to run the Azure PowerShell commands and docker commands in this article.

After installing Azure PowerShell, exit the SSH session.

Configure the VM with a user-assigned managed identity

A user-assigned managed identity is a standalone Azure resource that you manage separately from the resources that use it. You can associate a user-assigned managed identity with multiple Azure resources.

This section explains how to configure your VM with a user-assigned identity to securely access your Azure Container Registry.

Create a user-assigned managed identity

Azure CLI
Azure PowerShell

Create an identity in your subscription by using the az identity create command. You can use the same resource group you used previously to create the container registry or virtual machine, or choose a different one.

az identity create --resource-group myResourceGroup --name myACRId

To configure the identity in the following steps, use the az identity show command to store the identity's resource ID and service principal ID in variables.

# Get resource ID of the user-assigned identity
userID=$(az identity show --resource-group myResourceGroup --name myACRId --query id --output tsv)

# Get service principal ID of the user-assigned identity
spID=$(az identity show --resource-group myResourceGroup --name myACRId --query principalId --output tsv)

Because you need the identity's ID in a later step when you sign in to the CLI from your virtual machine, show the value:

echo $userID

The ID is of the form:

/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myACRId

Create an identity in your subscription by using the New-AzUserAssignedIdentity cmdlet. You can use the same resource group you used previously to create the container registry or virtual machine, or choose a different one.

New-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Location eastus -Name myACRId

To configure the identity in the following steps, use the Get-AzUserAssignedIdentity cmdlet to store the identity's resource ID and service principal ID in variables.

# Get resource ID of the user-assigned identity
$userID = (Get-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Name myACRId).Id

# Get service principal ID of the user-assigned identity
$spID = (Get-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Name myACRId).PrincipalId

Because you need the identity's ID in a later step when you sign in to the Azure PowerShell from your virtual machine, show the value:

$userID

The ID is of the form:

/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myACRId

Configure the VM with the user-assigned managed identity

Next, configure your Docker VM to use the user-assigned identity you created in the previous step.

Azure CLI
Azure PowerShell

Use az vm identity assign to configure the VM, using the ID you retrieved in the previous step:

az vm identity assign --resource-group myResourceGroup --name myDockerVM --identities $userID

Use Update-AzVM to configure the VM, using the ID you retrieved in the previous step:

$vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myDockerVM
Update-AzVM -ResourceGroupName myResourceGroup -VM $vm -IdentityType UserAssigned -IdentityID $userID

Grant the user-assigned managed identity access to the container registry

Now configure the identity so that it has access to your container registry.

You must assign either Container Registry Repository Reader (for ABAC-enabled registries) or AcrPull (for non-ABAC registries). This role assignment provides pull permissions to the registry.

To provide both pull and push permissions, assign either the Container Registry Repository Writer role for ABAC-enabled registries, or the AcrPush role for non-ABAC-enabled registries.

Azure CLI
Azure PowerShell

Use az acr show to get the resource ID of the registry:

resourceID=$(az acr show --resource-group myResourceGroup --name myContainerRegistry --query id --output tsv)

Use az role assignment create to assign the desired role to the identity. This example assigns the Container Registry Repository Reader role, which grants pull permissions only, on an ABAC-enabled registry:

az role assignment create --assignee $spID --scope $resourceID \
    --role "Container Registry Repository Reader" # For ABAC-enabled registries. Otherwise, use AcrPull for non-ABAC registries.

Use Get-AzContainerRegistry to get the resource ID of the registry:

$resourceID = (Get-AzContainerRegistry -ResourceGroupName myResourceGroup -Name myContainerRegistry).Id

Use New-AzRoleAssignment to assign the desired role to the identity. This example assigns the Container Registry Repository Reader role, which grants pull permissions only, on an ABAC-enabled registry:

New-AzRoleAssignment -ObjectId $spID -Scope $resourceID -RoleDefinitionName "Container Registry Repository Reader"

Use the user-assigned managed identity to access the registry

SSH into the Docker virtual machine that the identity configures, and then run the following commands to enable the identity to access your container registry.

Azure CLI
Azure PowerShell

On the VM, authenticate to the Azure CLI by using az login, using the identity you retrieved earlier.

az login --identity --username <userID>

Next, authenticate to the registry by using az acr login. When you use this command, the CLI uses the Active Directory token created when you ran az login to seamlessly authenticate your session with the container registry.

az acr login --name myContainerRegistry

You should see a Login succeeded message. You can then run docker commands without providing credentials. For example, run docker pull to pull the aci-helloworld:v1 image, specifying the login server name of your registry:

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

On the VM, authenticate to Azure PowerShell by using Connect-AzAccount, using the ID you retrieved earlier. For -AccountId, specify a client ID of the identity.

$clientId = (Get-AzUserAssignedIdentity -ResourceGroupName myResourceGroup -Name myACRId).ClientId
Connect-AzAccount -Identity -AccountId $clientId

Next, authenticate to the registry by using Connect-AzContainerRegistry. When you use this command, Azure PowerShell uses the Active Directory token created when you ran Connect-AzAccount to seamlessly authenticate your session with the container registry.

Connect-AzContainerRegistry -Name myContainerRegistry

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

Configure the VM with a system-assigned managed identity

A system-assigned managed identity is a feature of Azure that allows your virtual machine to automatically manage its own identity in Azure Active Directory. This section explains how to configure your VM with a system-assigned identity to securely access your Azure Container Registry.

Enable the system-assigned managed identity on your VM

Azure CLI
Azure PowerShell

Use az vm identity assign to configure your Docker VM with a system-assigned identity:

az vm identity assign --resource-group myResourceGroup --name myDockerVM

Use az vm show to set a variable to the value of principalId (the service principal ID) of the VM's identity, to use in later steps:

spID=$(az vm show --resource-group myResourceGroup --name myDockerVM --query identity.principalId --out tsv)

Use Update-AzVM to configure your Docker VM with a system-assigned identity:

$vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myDockerVM
Update-AzVM -ResourceGroupName myResourceGroup -VM $vm -IdentityType SystemAssigned

Use Get-AzVM to set a variable to the value of principalId (the service principal ID) of the VM's identity, to use in later steps:

$spID = (Get-AzVM -ResourceGroupName myResourceGroup -Name myDockerVM).Identity.PrincipalId

Grant the system-assigned managed identity access to the container registry

Now configure the identity so that it has access to your container registry.

You must assign either Container Registry Repository Reader (for ABAC-enabled registries) or AcrPull (for non-ABAC registries). This role assignment provides pull permissions to the registry.

To provide both pull and push permissions, assign either the Container Registry Repository Writer role for ABAC-enabled registries, or the AcrPush role for non-ABAC-enabled registries.

Azure CLI
Azure PowerShell

Use az acr show to get the resource ID of the registry:

resourceID=$(az acr show --resource-group myResourceGroup --name myContainerRegistry --query id --output tsv)

az role assignment create --assignee $spID --scope $resourceID \
    --role "Container Registry Repository Reader"

Use Get-AzContainerRegistry to get the resource ID of the registry:

$resourceID = (Get-AzContainerRegistry -ResourceGroupName myResourceGroup -Name myContainerRegistry).Id

Use New-AzRoleAssignment to assign the correct role to the identity. This example assigns the Container Registry Repository Reader role, which grants pull permissions only, on an ABAC-enabled registry:

New-AzRoleAssignment -ObjectId $spID -Scope $resourceID -RoleDefinitionName "Container Registry Repository Reader"

Use the system-assigned managed identity to access the registry

SSH into the Docker virtual machine that the identity configures, and then run the following commands to enable the identity to access your container registry.

Azure CLI
Azure PowerShell

On the VM, authenticate the Azure CLI by using az login, using the system-assigned identity.

az login --identity

Next, authenticate to the registry by using az acr login. When you use this command, the CLI uses the Active Directory token created when you ran az login to seamlessly authenticate your session with the container registry.

az acr login --name myContainerRegistry

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

On the VM, authenticate the Azure PowerShell by using Connect-AzAccount, using the system-assigned identity.

Connect-AzAccount -Identity

Next, authenticate to the registry by using Connect-AzContainerRegistry. When you use this command, the PowerShell uses the Active Directory token created when you ran Connect-AzAccount to seamlessly authenticate your session with the container registry.

Connect-AzContainerRegistry -Name myContainerRegistry

docker pull mycontainerregistry.azurecr.io/aci-helloworld:v1

Learn more about managed identities for Azure resources.
Learn how to use a system-assigned or user-assigned managed identity with App Service and Azure Container Registry.
Learn how to deploy a container image from Azure Container Registry using a managed identity.

Feedback

Was this page helpful?

Last updated on 2026-02-04