az role assignment create: Grant RBAC Roles
az role assignment create grants a built-in or custom RBAC role to a principal at a given scope.
Most CI authorization failures end with a role assignment. Granting Storage Blob Data Contributor or AcrPull to the pipeline identity is the usual fix.
What it does
az role assignment create binds a role definition to a principal (user, group, or service principal) at a scope (subscription, group, or resource). The assignment authorizes that identity to perform the role actions within the scope.
Common usage
az role assignment create \
--assignee 00000000-0000-0000-0000-000000000000 \
--role "Storage Blob Data Contributor" \
--scope "/subscriptions/<sub>/resourceGroups/rg-app"
# AcrPull on a single registry
az role assignment create --assignee-object-id <oid> \
--assignee-principal-type ServicePrincipal \
--role AcrPull --scope <registry-resource-id>Subcommands and flags
| Flag | What it does |
|---|---|
| --assignee | Principal by appId, object id, or UPN |
| --assignee-object-id | Principal by object id (avoids a graph lookup) |
| --role | Role name or definition id |
| --scope | Resource id the role applies to |
| --assignee-principal-type | User, Group, or ServicePrincipal |
In CI
Prefer --assignee-object-id with --assignee-principal-type ServicePrincipal so the command does not need Graph read permission to resolve the principal. Role assignments take a short time to propagate, so a deploy step immediately after may still see AuthorizationFailed; retry with a brief delay.
Common errors in CI
"The role assignment already exists" means a rerun; treat it as success or check existence first. "Cannot find user or service principal in graph database" means --assignee could not be resolved; pass --assignee-object-id instead. "AuthorizationFailed" on the create itself means the caller lacks Owner or User Access Administrator at the scope.