Use an Azure managed identity to authenticate to an Azure container registry

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 this article, you learn more about managed identities and how to:

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

Azure CLI

To create the Azure resources, this article requires that you run the Azure CLI version 2.0.55 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

Azure PowerShell

To create the Azure resources, this article requires that you run the Azure PowerShell module version 7.5.0 or later. Run Get-Module Az -ListAvailable to find the version. If you need to install or upgrade, see Install Azure PowerShell module.

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.

Why use a managed identity?

If you're not familiar with the managed identities for Azure resources feature, see this overview.

After you set up selected Azure resources with a managed identity, give the identity the access you want to another resource, just like any security principal. For example, assign a managed identity a role with pull, push and pull, or other permissions to a private registry in Azure. (For a complete list of registry roles, see Azure Container Registry roles and permissions.) You can give an identity access to one or more resources.

Then, use the identity to authenticate to any service that supports Microsoft Entra authentication, without any credentials in your code. Choose how to authenticate using the managed identity, depending on your scenario. To use the identity to access an Azure container registry from a virtual machine, you authenticate with Azure Resource Manager.

Create a container registry

Azure CLI

If you don't already have an Azure container registry, create a registry and push a sample container image to it. For steps, see Quickstart: Create a private container registry using the Azure CLI.

This article assumes you have the aci-helloworld:v1 container image stored in your registry. The examples use a registry name of myContainerRegistry. Replace with your own registry and image names in later steps.

Azure PowerShell

If you don't already have an Azure container registry, create a registry and push a sample container image to it. For steps, see Quickstart: Create a private container registry using Azure PowerShell.

This article assumes you have the aci-helloworld:v1 container image stored in your registry. The examples use a registry name of myContainerRegistry. Replace with your own registry and image names in later steps.

Create a Docker-enabled VM

Azure CLI

Create a Docker-enabled Ubuntu virtual machine. You also need to install the Azure CLI on the virtual machine. If you already have an Azure virtual machine, skip this step to create the virtual machine.

Deploy a default Ubuntu Azure virtual machine with 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 for the VM to be created. When the command completes, take note of the publicIpAddress displayed by the Azure CLI. Use this address to make SSH connections to the VM.

Azure PowerShell

Create a Docker-enabled Ubuntu virtual machine. You also need to install the Azure PowerShell on the virtual machine. If you already have an Azure virtual machine, skip this step to create the virtual machine.

Deploy a default Ubuntu Azure virtual machine with New-AzVM. The following example creates a VM named myDockerVM in an existing resource group named myResourceGroup. You will be prompted for a user name that will be used when you connect to the VM. Specify azureuser as the user name. You will also be asked for a password, which you can leave blank. Password login 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 for the VM to be created. When the command completes, run the following command to get the public IP address. Use this address to make SSH connections to the VM.

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

Install Docker on the VM

To run Docker containers on your virtual machine, you need to install Docker. This section provides the steps to install Docker on an Ubuntu VM, ensuring that your VM is ready to pull and run container images from your Azure Container Registry.

After 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.
[...]

Azure CLI

Install the Azure CLI

Follow the steps in Install Azure CLI with apt to install the Azure CLI on your Ubuntu virtual machine. For this article, ensure that you install version 2.0.55 or later.

Azure PowerShell

Install the Azure PowerShell

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, ensure that you install Azure PowerShell version 7.5.0 or later.

Exit the SSH session.

Example 1: Access with a user-assigned identity

Create an identity

Azure CLI

Create an identity in your subscription 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 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

Azure PowerShell

Create an identity in your subscription using the New-AzUserAssignedIdentity cmdlet. You can use the same resource group you used previously to create the container registry or virtual machine, or 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 identity

Azure CLI

The following az vm identity assign command configures your Docker VM with the user-assigned identity:

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

Azure PowerShell

The following Update-AzVM command configures your Docker VM with the user-assigned identity:

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

Grant identity access to the container registry

Azure CLI

Now configure the identity to access your container registry. First use the az acr show command to get the resource ID of the registry:

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

Use the az role assignment create command to assign the AcrPull role to the identity. This role provides pull permissions to the registry. To provide both pull and push permissions, assign the AcrPush role.

az role assignment create --assignee $spID --scope $resourceID --role acrpull

Azure PowerShell

Now configure the identity to access your container registry. First use the Get-AzContainerRegistry command to get the resource ID of the registry:

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

Use the New-AzRoleAssignment cmdlet to assign the AcrPull role to the identity. This role provides pull permissions to the registry. To provide both pull and push permissions, assign the AcrPush role.

New-AzRoleAssignment -ObjectId $spID -Scope $resourceID -RoleDefinitionName AcrPull

Use the identity to access the registry

Azure CLI

SSH into the Docker virtual machine that's configured with the identity. Run the following Azure CLI commands, using the Azure CLI installed on the VM.

First, authenticate to the Azure CLI with az login, using the identity you configured on the VM. For <userID>, substitute the ID of the identity you retrieved in a previous step.

az login --identity --username <userID>

Then, authenticate to the registry with 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. (Depending on your VM's setup, you might need to run this command and docker commands with sudo.)

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. The login server name consists of your container registry name (all lowercase) followed by .azurecr.io - for example, mycontainerregistry.azurecr.io.

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

Azure PowerShell

SSH into the Docker virtual machine that's configured with the identity. Run the following Azure PowerShell commands, using the Azure PowerShell installed on the VM.

First, authenticate to the Azure PowerShell with Connect-AzAccount, using the identity you configured on the VM. For -AccountId specify a client ID of the identity.

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

Then, authenticate to the registry with Connect-AzContainerRegistry. When you use this command, the Azure PowerShell uses the Active Directory token created when you ran Connect-AzAccount to seamlessly authenticate your session with the container registry. (Depending on your VM's setup, you might need to run this command and docker commands with sudo.)

sudo pwsh -command Connect-AzContainerRegistry -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. The login server name consists of your container registry name (all lowercase) followed by .azurecr.io - for example, mycontainerregistry.azurecr.io.

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

Configure the VM with a system-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.

Configure the VM with a system-managed identity

Azure CLI

The following az vm identity assign command configures your Docker VM with a system-assigned identity:

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

Use the az vm show command 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)

Azure PowerShell

The following Update-AzVM command configures your Docker VM with a system-assigned identity:

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

Use the Get-AzVM command 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 identity access to the container registry

Azure CLI

Now configure the identity to access your container registry. First use the az acr show command to get the resource ID of the registry:

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

Use the az role assignment create command to assign the AcrPull role to the identity. This role provides pull permissions to the registry. To provide both pull and push permissions, assign the AcrPush role.

az role assignment create --assignee $spID --scope $resourceID --role acrpull

Azure PowerShell

Now configure the identity to access your container registry. First use the [Get-AzContainerRegistry command to get the resource ID of the registry:

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

Use the New-AzRoleAssignment cmdlet to assign the AcrPull role to the identity. This role provides pull permissions to the registry. To provide both pull and push permissions, assign the AcrPush role.

New-AzRoleAssignment -ObjectId $spID -Scope $resourceID -RoleDefinitionName AcrPull

Use the identity to access the registry

Azure CLI

SSH into the Docker virtual machine that's configured with the identity. Run the following Azure CLI commands, using the Azure CLI installed on the VM.

First, authenticate the Azure CLI with az login, using the system-assigned identity on the VM.

az login --identity

Then, authenticate to the registry with 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. (Depending on your VM's setup, you might need to run this command and docker commands with sudo.)

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. The login server name consists of your container registry name (all lowercase) followed by .azurecr.io - for example, mycontainerregistry.azurecr.io.

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

Azure PowerShell

SSH into the Docker virtual machine that's configured with the identity. Run the following Azure PowerShell commands, using the Azure PowerShell installed on the VM.

First, authenticate the Azure PowerShell with Connect-AzAccount, using the system-assigned identity on the VM.

Connect-AzAccount -Identity

Then, authenticate to the registry with 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. (Depending on your VM's setup, you might need to run this command and docker commands with sudo.)

sudo pwsh -command Connect-AzContainerRegistry -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. The login server name consists of your container registry name (all lowercase) followed by .azurecr.io - for example, mycontainerregistry.azurecr.io.

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

Next steps

In this article, you learned about using managed identities with Azure Container Registry and how to:

• Enable a user-assigned or system-assigned identity in an Azure VM
• Grant the identity access to an Azure container registry
• Use the managed identity to access the registry and pull a container image

• 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.