Edit

Share via

Azure Container Registry Entra permissions and role assignments overview

  • Article

Azure Container Registry (ACR) offers a set of built-in roles that provide Microsoft Entra-based permissions management to an ACR registry. Using Azure role-based access control (RBAC), you can assign a built-in role to users, managed identities, or service principals to grant Microsoft Entra-based permissions defined within the role. You can also define and assign custom roles with fine-grained permissions tailored to your specific needs if the built-in roles don't meet your requirements.

Supported role assignment identity types

ACR roles can be assigned to the following identity types to grant permissions to a registry:

Take note that ACR connected registry, ACR's on-premises registry offering that differs from cloud-based ACR, doesn't support Azure role assignments and Entra-based permissions management.

Performing role assignments to grant permissions

See Steps to add a role assignment for information on how to assign a role to an identity. Role assignments can be made using:

To perform role assignments, you must either have the Owner role or Role Based Access Control Administrator role on the registry.

Scoping role assignments to specific repositories

You can use Microsoft Entra attribute-based access control (ABAC) for managing Microsoft Entra-based repository permissions. This feature allows you to scope role assignments to specific repositories in a registry.

For an overview of Microsoft Entra ABAC repository permissions, including the ACR built-in roles that support Microsoft Entra ABAC conditions, see Microsoft Entra-based repository permissions. Alternatively, you can consult the Azure Container Registry roles directory reference for a list of built-in roles that support Microsoft Entra ABAC conditions.

Apply the principle of least privilege by assigning only the permissions necessary for an identity to perform its intended function. These common scenarios each have a recommended built-in role.

Note

The applicable built-in roles and role behavior depends on the registry's "Role assignment permissions mode". This is visible in the "Properties" blade in the Azure portal:

  • RBAC Registry + ABAC Repository Permissions: Supports standard RBAC role assignments with optional Microsoft Entra ABAC conditions to scope assignments to specific repositories.
  • RBAC Registry Permissions: Supports only standard RBAC assignments without ABAC conditions. For details on Microsoft Entra ABAC and ABAC-enabled roles, see Microsoft Entra-based repository permissions.

  • Scenario: Identities that need to pull images and validate supply chain artifacts such as developers, pipelines, and container orchestrators (for example, Azure Kubernetes Service node kubelet identity, Azure Container Apps, Azure Container Instances, Azure Machine Learning workspaces)

    • Role: Container Registry Repository Reader
    • Purpose: Grants data plane read-only access to pull images and artifacts, view tags, repositories, Open Container Initiative (OCI) referrers, and artifact streaming configurations. Doesn't include any control plane or write permissions. Doesn't grant repository catalog list permissions to list any repositories in the registry.
    • ABAC support: This role supports optional Microsoft Entra ABAC conditions to scope role assignments to specific repositories in the registry.

  • Scenario: Identities such as CI/CD build pipelines and developers that build and push images, as well as manage image tags

    • Role: Container Registry Repository Writer
    • Permissions: Grants data plane access to push, pull, and update (but not delete) images and artifacts, read/manage tags, read/manage OCI referrers, and enable (but not disable) artifact streaming for repositories and images. Doesn't include any control plane permissions. Doesn't grant repository catalog list permissions to list any repositories in the registry.
    • ABAC support: This role supports optional Microsoft Entra ABAC conditions to scope role assignments to specific repositories in the registry.

  • Scenario: Identities that need to delete images, artifacts, tags, and OCI referrers

    • Role: Container Registry Repository Contributor
    • Permissions: Grants permissions to read, write, update, and delete images and artifacts, read/manage/delete tags, read/manage/delete OCI referrers, and enable/disable artifact streaming for repositories and images. Doesn't include any control plane permissions. Doesn't grant repository catalog list permissions to list any repositories in the registry.
    • ABAC support: This role supports optional Microsoft Entra ABAC conditions to scope role assignments to specific repositories in the registry.

  • Scenario: Identities that need to list all repositories in the registry

    • Role: Container Registry Repository Catalog Lister
    • Permissions: Grants data plane access to list all repositories in the registry, including through the {loginServerURL}/acr/v1/_catalog or {loginServerURL}/v2/_catalog registry API endpoints. Doesn't include any control plane permissions or permissions to push/pull images.
    • ABAC support: This role doesn't support Microsoft Entra ABAC conditions. As such, this role assignment will grant permissions to list all repositories in the registry.

  • Scenario: Pipelines, identities, and developers that sign images

    • For signing images with OCI referrers such as Notary Project:
      • Role: Container Registry Repository Writer
      • Permissions: Grants data plane access to push signatures in the form of OCI referrers attached to images and artifacts. Doesn't include any control plane permissions.
      • ABAC support: This role supports optional Microsoft Entra ABAC conditions to scope role assignments to specific repositories in the registry.
    • For signing images with Docker Content Trust (DCT):
      • Signing images with DCT for ABAC-enabled registries is not supported.

  • Scenario: Pipelines, identities, and developers that need to create, update, or delete ACR registries

  • Scenario: Pipelines, infrastructure engineers, or control plane observability/monitoring tools that need to list registries and view registry configurations, but not access to registry images

    • Role: Container Registry Configuration Reader and Data Access Configuration Reader
    • Permissions: Read-only counterpart of the Container Registry Contributor and Data Access Configuration Administrator role. Grants control plane access to view and list registries and inspect registry configurations, but not modify them. Doesn't include data plane operations (for example, image push/pull) or role assignment capabilities.
    • ABAC support: This role doesn't support Microsoft Entra ABAC conditions as the role is scoped to the registry level, granting permissions to read control plane settings and configurations for the entire registry.

  • Scenario: Vulnerability scanners and tools that need to audit registries and registry configurations, as well as access to registry images to scan them for vulnerabilities

    • Roles: Container Registry Repository Reader, Container Registry Repository Catalog Lister, and Container Registry Configuration Reader and Data Access Configuration Reader
    • Permissions: Grants control plane access to view and list ACR registries, as well as to audit registry configurations for audit and compliance. Also grants permissions to pull images, artifacts, and view tags to scan and analyze images for vulnerabilities.
    • ABAC support: ACR recommends that vulnerability scanners and monitors have full data plane access to all repositories in the registry. As such, these roles should be assigned without Microsoft Entra ABAC conditions to grant role permissions without scoping them to specific repositories.

  • Scenario: Pipelines and identities that orchestrate ACR tasks

  • Scenario: Identities such as pipelines and developers that import images with az acr import

    • Role: Container Registry Data Importer and Data Reader
    • Permissions: Grants control plane access to trigger image imports using az acr import, and data plane access to validate import success (pull imported images and artifacts, view repository contents, list OCI referrers, and inspect imported tags). Doesn't allow pushing or modifying any content in the registry.
    • ABAC support: This role doesn't support Microsoft Entra ABAC conditions as the role is scoped to the registry level, granting permissions to import images into any repository in the registry. It also grants permissions to read images in all repositories in the registry.

  • Scenario: Identities such as pipelines and developers that manage ACR transfer pipelines for transferring artifacts between registries using intermediary storage accounts across network, tenant, or air gap boundaries

    • Role: Container Registry Transfer Pipeline Contributor
    • Permissions: Grants control plane access to manage ACR import/export transfer pipelines and pipeline runs using intermediary storage accounts. Doesn't include data plane permissions, broader registry access, or permissions to manage other Azure resource types such as storage accounts or key vaults.
    • ABAC support: This role doesn't support Microsoft Entra ABAC conditions as the role is scoped to the registry level, granting permissions to manage all ACR transfer pipelines in the registry.

  • Scenario: Management of quarantined images

    • Roles: AcrQuarantineReader and AcrQuarantineWriter
    • Permissions: Manage quarantined images in the registry, including listing and pulling quarantined images for further inspection, and modifying the quarantine status of images. Quarantined images are pushed images that can't be pulled or used until they're unquarantined.
    • ABAC support: This role doesn't support Microsoft Entra ABAC conditions as the role is scoped to the registry level, granting permissions to manage all quarantined images in the registry.

  • Scenario: Developers or processes that configure registry auto-purge on ACR Tasks

    • Role: Container Registry Tasks Contributor
    • Permissions: Grants control plane permissions to manage auto-purge, which runs on ACR Tasks.
    • ABAC support: This role doesn't support Microsoft Entra ABAC conditions as the role is scoped to the registry level, granting permissions to manage all ACR Tasks in the registry.

  • Scenario: Visual Studio Code Docker extension users

    • Roles: Container Registry Repository Writer, Container Registry Tasks Contributor, and Container Registry Contributor and Data Access Configuration Administrator
    • Permissions: Grants capabilities to browse registries, pull and push images, and build images using az acr build, supporting common developer workflows in Visual Studio Code.
    • ABAC support: ACR recommends that Visual Studio Code users have full data plane access to all repositories in the registry. As such, these roles should be assigned without Microsoft Entra ABAC conditions to grant role permissions without scoping them to specific repositories.

Next steps