Azure Container Registry custom roles

2025-06-23

Azure Container Registry (ACR) supports Azure role-based access control (RBAC) to manage access to your registry. If none of the Azure Container Registry built-in roles suit your needs, you can create custom roles with fine-grained permissions tailored to your scenario. This article describes the steps to define, create, and assign custom roles for Azure Container Registry.

Custom role permissions

A set of permissions (actions and data actions) define a custom role. The permissions defined in the custom role determine what operations users can perform on registry resources.

To determine which permissions (actions and data actions) should be defined in a custom role, you can:

Review the JSON definition of Azure built-in roles directory for Containers which includes commonly used permissions (actions and data actions) that are used in ACR built-in roles,
Review the complete list of Microsoft.ContainerRegistry resource provider permissions (Azure Container Registry reference of actions and data actions)

To programmatically list all available permissions (actions and data actions) for the Microsoft.ContainerRegistry resource provider, you can use the following Azure CLI or Azure PowerShell commands.

az provider operation show --namespace Microsoft.ContainerRegistry

Get-AzProviderOperation -OperationSearchString Microsoft.ContainerRegistry/*

Example: Custom role to manage webhooks

For example, the following JSON defines the minimum permissions (actions and data actions) for a custom role that permits managing ACR webhooks.

{
   "assignableScopes": [
     "/subscriptions/<optional, but you can limit the visibility to one or more subscriptions>"
   ],
   "description": "Manage Azure Container Registry webhooks.",
   "Name": "Container Registry Webhook Contributor",
   "permissions": [
     {
       "actions": [
         "Microsoft.ContainerRegistry/registries/webhooks/read",
         "Microsoft.ContainerRegistry/registries/webhooks/write",
         "Microsoft.ContainerRegistry/registries/webhooks/delete"
       ],
       "dataActions": [],
       "notActions": [],
       "notDataActions": []
     }
   ],
   "roleType": "CustomRole"
 }

Creating or updating a custom role

To define a custom role with a JSON definition, see steps to create a custom role. You can create the custom role using Azure CLI, Azure Resource Manager template, or Azure PowerShell.

Note

In tenants configured with Azure Resource Manager private link , Azure Container Registry supports wildcard actions such as Microsoft.ContainerRegistry/*/read or Microsoft.ContainerRegistry/registries/*/write in custom roles, granting access to all matching actions. In a tenant without an ARM private link, don't use wildcards and specify all required registry actions individually in a custom role.

Assigning a custom role

Add or remove role assignments for a custom role in the same way that you manage role assignments for built-in roles. Learn more about assigning Azure roles to an Azure identity by using the Azure portal, the Azure CLI, Azure PowerShell, or other Azure tools.

Next steps

For a high-level overview of these built-in roles—including supported role assignment identity types, steps to perform a role assignment, and recommended roles for common scenarios—see Azure Container Registry RBAC built-in roles.
To perform role assignments with optional Microsoft Entra ABAC conditions to scope role assignments to specific repositories, see Microsoft Entra-based repository permissions.
For a detailed reference of every ACR built-in role, including the permissions granted by each role, see the Azure Container Registry roles directory reference.