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

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.

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.

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.

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

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

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.

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

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 chinaeast2 -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

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

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

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

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

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 cloud set -n AzureChinaCloud
az login --identity --username <userID>
# az cloud set -n AzureCloud   //means return to Public Azure.

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.cn - for example, mycontainerregistry.azurecr.cn.

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

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 -Environment AzureChinaCloud, 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 -Environment AzureChinaCloud -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 -Environment AzureChinaCloud 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.cn - for example, mycontainerregistry.azurecr.cn.

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

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)

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

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

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

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 cloud set -n AzureChinaCloud
az login --identity
# az cloud set -n AzureCloud   //means return to Public Azure.

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.cn - for example, mycontainerregistry.azurecr.cn.

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

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 -Environment AzureChinaCloud, using the system-assigned identity on the VM.

Connect-AzAccount -Environment AzureChinaCloud -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 -Environment AzureChinaCloud 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.cn - for example, mycontainerregistry.azurecr.cn.

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