Use an Azure-managed identity in ACR Tasks

Enable a managed identity for Azure resources in an ACR task, so the task can access other Azure resources, without needing to provide or manage credentials. For example, use a managed identity to enable a task step to pull or push container images to another registry.

In this article, you learn how to use the Azure CLI to enable a user-assigned or system-assigned managed identity on an ACR task. You can use the Azure Cloud Shell or a local installation of the Azure CLI. If you'd like to use it locally, version 2.0.68 or later is required. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.

For scenarios to access secured resources from an ACR task using a managed identity, see:

Why use a managed identity?

A managed identity for Azure resources provides selected Azure services with an automatically managed identity in Azure Active Directory (Azure AD). You can configure an ACR task with a managed identity so that the task can access other secured Azure resources, without passing credentials in the task steps.

Managed identities are of two types:

  • User-assigned identities, which you can assign to multiple resources and persist for as long as you want. User-assigned identities are currently in preview.

  • A system-assigned identity, which is unique to a specific resource such as an ACR task and lasts for the lifetime of that resource.

You can enable either or both types of identity in an ACR task. Grant the identity access to another resource, just like any security principal. When the task runs, it uses the identity to access the resource in any task steps that require access.

Steps to use a managed identity

Follow these high-level steps to use a managed identity with an ACR task.

1. (Optional) Create a user-assigned identity

If you plan to use a user-assigned identity, you can use an existing identity. Or, create the identity using the Azure CLI or other Azure tools. For example, use the az identity create command.

If you plan to use only a system-assigned identity, skip this step. You can create a system-assigned identity when you create the ACR task.

2. Enable identity on an ACR task

When you create an ACR task, optionally enable a user-assigned identity, a system-assigned identity, or both. For example, pass the --assign-identity parameter when you run the az acr task create command in the Azure CLI.

To enable a system-assigned identity, pass --assign-identity with no value or assign-identity [system]. The following command creates a Linux task from a public GitHub repository which builds the hello-world image with a Git commit trigger and with a system-assigned managed identity:

az acr task create \
    --image hello-world:{{.Run.ID}} \
    --name hello-world --registry MyRegistry \
    --context https://github.com/Azure-Samples/acr-build-helloworld-node.git \
    --file Dockerfile \
    --assign-identity

To enable a user-assigned identity, pass --assign-identity with a value of the resource ID of the identity. The following command creates a Linux task from a public GitHub repository which builds the hello-world image with a Git commit trigger and with a user-assigned managed identity:

az acr task create \
    --image hello-world:{{.Run.ID}} \
    --name hello-world --registry MyRegistry \
    --context https://github.com/Azure-Samples/acr-build-helloworld-node.git \
    --file Dockerfile \
    --assign-identity <resourceID>

You can get the resource ID of the identity by running the az identity show command. The resource ID for the ID myUserAssignedIdentity in resource group myResourceGroup is of the form.

"/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myUserAssignedIdentity"

3. Grant the identity permissions to access other Azure resources

Depending on the requirements of your task, grant the identity permissions to access other Azure resources. Examples include:

  • Assign the managed identity a role with pull, push and pull, or other permissions to a target container registry in Azure. For a complete list of registry roles, see Azure Container Registry roles and permissions.
  • Assign the managed identity a role to read secrets in an Azure key vault.

Use the Azure CLI or other Azure tools to manage role-based access to resources. For example, run the az role assignment create command to assign the identity a role to the identity.

The following example assigns a managed identity the permissions to pull from a container registry. The command specifies the service principal ID of the identity and the resource ID of the target registry.

az role assignment create --assignee <servicePrincipalID> --scope <registryID> --role acrpull

4. (Optional) Add credentials to the task

If your task pulls or pushes images to another Azure container registry, add credentials to the task for the identity to authenticate. Run the az acr task credential add command and pass the --use-identity parameter to add the identity's credentials to the task.

For example, to add credentials for a system-assigned identity to authenticate with the registry targetregistry, pass use-identity [system]:

az acr task credential add \
    --name helloworld \
    --registry myregistry \
    --login-server targetregistry.azurecr.io \
    --use-identity [system]

To add credentials for a user-assigned identity to authenticate with the registry targetregistry, pass use-identity with a value of the client ID of the identity. For example:

az acr task credential add \
    --name helloworld \
    --registry myregistry \
    --login-server targetregistry.azurecr.io \
    --use-identity <clientID>

You can get the client ID of the identity by running the az identity show command. The client ID is a GUID of the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Next steps

In this article, you learned how to enable and use a user-assigned or system-assigned managed identity on an ACR task. For scenarios to access secured resources from an ACR task using a managed identity, see: