🚨 Azure Error Guide: 'AuthorizationFailed' RBAC Action Not Permitted Over Scope

Overview

An AuthorizationFailed error means Azure Resource Manager evaluated the caller’s effective permissions for a specific action over a specific scope and found no role assignment that grants it (or found a deny assignment / policy that blocks it). The request never reaches the resource provider — RBAC rejects it at the control plane. This is an authorization decision, not an authentication one: the token is valid, the identity is just not allowed to do that thing there.

You will see this from the CLI, portal, or an automation pipeline:

(AuthorizationFailed) The client 'pipeline-sp@contoso.com' with object id 'd4e5f6a7-1111-2222-3333-444455556666' does not have authorization to perform action 'Microsoft.Compute/virtualMachines/write' over scope '/subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod/providers/Microsoft.Compute/virtualMachines/web-01' or the scope is invalid. If access was recently granted, please refresh your credentials.
Code: AuthorizationFailed

And in an az invocation with --debug, the underlying 403 is logged:

urllib3.connectionpool : https://management.azure.com:443 "PUT /subscriptions/aaaa1111.../resourceGroups/rg-prod/providers/Microsoft.Compute/virtualMachines/web-01?api-version=2024-07-01 HTTP/1.1" 403 None
cli.azure.cli.core.sdk.policies : Response status: 403
cli.azure.cli.core.sdk.policies : 'x-ms-failure-cause': 'gateway'

It occurs whenever a principal (user, service principal, or managed identity) calls an action it lacks a grant for — most commonly in CI/CD pipelines, freshly created service principals, or after a subscription/role change has not yet propagated.

Symptoms

• A CLI or pipeline command fails with (AuthorizationFailed) and a 403, naming a specific action and scope.
• The same command works for an admin but fails for a service principal or a junior account.
• Access that “was just granted in the portal” still fails for a few minutes.
• Read operations succeed but a write/delete/action fails (partial permissions).

az role assignment list --assignee d4e5f6a7-1111-2222-3333-444455556666 \
  --scope /subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod \
  --include-inherited -o table

Principal                              Role     Scope
-------------------------------------  -------  -----------------------------------------------------
d4e5f6a7-1111-2222-3333-444455556666   Reader   /subscriptions/aaaa1111-.../resourceGroups/rg-prod

az account show -o table

Name           CloudName    SubscriptionId                        TenantId                              State    IsDefault
-------------  -----------  ------------------------------------  ------------------------------------  -------  -----------
Sandbox-Dev    AzureCloud   ffff9999-8888-7777-6666-555544443333  11112222-3333-4444-5555-666677778888  Enabled  True

Common Root Causes

1. No role assignment grants the action

The principal simply has no role at this scope that includes the requested action. A Reader cannot write; a Contributor cannot manage role assignments.

az role assignment list \
  --assignee d4e5f6a7-1111-2222-3333-444455556666 \
  --scope /subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod \
  --include-inherited -o table

Principal                              Role     Scope
-------------------------------------  -------  -----------------------------------------------------
d4e5f6a7-1111-2222-3333-444455556666   Reader   /subscriptions/aaaa1111-.../resourceGroups/rg-prod

Only Reader is present, so Microsoft.Compute/virtualMachines/write is denied.

2. Role is assigned at the wrong scope

The assignment exists but at a sibling resource group, a different subscription, or a child resource — not at (or above) the scope of the failing action. RBAC inherits downward, never upward.

az role assignment list \
  --assignee d4e5f6a7-1111-2222-3333-444455556666 \
  --all -o table

Principal                              Role          Scope
-------------------------------------  ------------  -------------------------------------------------------
d4e5f6a7-1111-2222-3333-444455556666   Contributor   /subscriptions/aaaa1111-.../resourceGroups/rg-staging

The grant is on rg-staging, but the action targets rg-prod — no inheritance applies.

3. A deny assignment blocks the action

Deny assignments (created by Blueprints, managed apps, or Azure-managed resources) take precedence over every role assignment. Even an Owner is blocked.

az role assignment list --assignee d4e5f6a7-1111-2222-3333-444455556666 \
  --scope /subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod \
  --include-inherited --include-groups -o json --query "[].roleDefinitionName"
az rest --method get \
  --url "https://management.azure.com/subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod/providers/Microsoft.Authorization/denyAssignments?api-version=2022-04-01" \
  --query "value[].{name:properties.denyAssignmentName, actions:properties.permissions[0].actions}"

[
  {
    "name": "DenyManagedApp-Compute",
    "actions": [ "Microsoft.Compute/virtualMachines/write" ]
  }
]

A deny assignment explicitly forbids the write — role assignments cannot override it.

4. Azure Policy is denying the action

A deny policy effect can block resource creation/modification even when RBAC permits it. The error may surface as RequestDisallowedByPolicy rather than AuthorizationFailed, but the symptom (403/blocked write) is the same and easily confused.

az policy state list \
  --resource /subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod \
  --filter "complianceState eq 'NonCompliant'" \
  --query "[].{policy:policyDefinitionName, effect:policyDefinitionAction}" -o table

Policy                                  Effect
--------------------------------------  ------
require-tag-costcenter-on-vm            deny

A deny policy (here requiring a tag) rejects the VM write before it is created.

5. Propagation delay or stale token

A newly added role assignment can take time to replicate, and a cached token issued before the change does not reflect new group memberships or claims. The principal is authorized, but the gateway has not caught up.

az account get-access-token --query "expiresOn" -o tsv
az account show --query user -o json

2026-06-23 13:58:42.000000
{
  "name": "pipeline-sp@contoso.com",
  "type": "servicePrincipal"
}

Re-authenticate to force a fresh token (az logout / az login, or az account clear for a service principal) and retry after a few minutes.

6. Wrong subscription or tenant context

The CLI is operating against the wrong active subscription or signed in to the wrong tenant, so the action targets a scope where the principal genuinely has no rights.

az account show --query "{sub:name, subId:id, tenant:tenantId}" -o json
az account list --query "[].{name:name, id:id, tenant:tenantId, default:isDefault}" -o table

{
  "sub": "Sandbox-Dev",
  "subId": "ffff9999-8888-7777-6666-555544443333",
  "tenant": "11112222-3333-4444-5555-666677778888"
}

The failing scope is in subscription aaaa1111-..., but the active context is ffff9999-... — set the correct one with az account set --subscription.

7. Custom role missing the action or dataAction

A custom role definition may omit the exact action, list it under notActions, or grant a control-plane action while the call needs a dataAction (or vice versa). Data-plane operations (blob read, key get) require dataActions, not actions.

az role definition list --custom-role-only true \
  --name "Prod VM Operator" \
  --query "[0].permissions[0].{actions:actions, notActions:notActions, dataActions:dataActions}" -o json
az provider operation show --namespace Microsoft.Compute \
  --query "resourceTypes[?name=='virtualMachines'].operations[?contains(name,'write')].name" -o json

{
  "actions": [ "Microsoft.Compute/virtualMachines/read", "Microsoft.Compute/virtualMachines/start/action" ],
  "notActions": [],
  "dataActions": null
}

The custom role lacks Microsoft.Compute/virtualMachines/write, so the write is denied despite the role being assigned.

Diagnostic Workflow

Step 1: Capture the exact action, scope, and principal from the error

az vm create -g rg-prod -n web-01 --image Ubuntu2204 --debug 2>&1 \
  | grep -iE "AuthorizationFailed|does not have authorization|object id"

The message names the action, the scope, and the principal object id — every later step keys off these three values.

Step 2: Confirm the active subscription and identity

az account show --query "{sub:name, subId:id, tenant:tenantId, user:user.name}" -o json

If the subscription or tenant is wrong, fix it before anything else:

az account set --subscription aaaa1111-bbbb-cccc-dddd-eeee22223333

Step 3: List effective role assignments at the failing scope

az role assignment list \
  --assignee <OBJECT_ID> \
  --scope <FAILING_SCOPE> \
  --include-inherited --include-groups -o table

If nothing grants the action, the fix is a missing/wrong-scope assignment. If a role is present, inspect what it actually permits.

Step 4: Resolve the role’s permissions and check for deny

az role definition list --name "<ROLE_NAME>" \
  --query "[0].permissions[0].{actions:actions, notActions:notActions, dataActions:dataActions}" -o json
az rest --method get \
  --url "https://management.azure.com<FAILING_SCOPE>/providers/Microsoft.Authorization/denyAssignments?api-version=2022-04-01" \
  --query "value[].properties.denyAssignmentName"

A notActions match or a deny assignment explains an otherwise-correct grant.

Step 5: Rule out policy, then refresh credentials and retry

az policy state list --resource <FAILING_SCOPE> \
  --filter "complianceState eq 'NonCompliant'" -o table
az account clear && az login   # or re-acquire the SP token

After fixing the assignment/scope/policy and refreshing the token, re-run the original command.

Example Root Cause Analysis

A release pipeline using the service principal pipeline-sp starts failing on az vm create into rg-prod with:

(AuthorizationFailed) The client 'pipeline-sp@contoso.com' with object id 'd4e5f6a7-1111-2222-3333-444455556666' does not have authorization to perform action 'Microsoft.Compute/virtualMachines/write' over scope '/subscriptions/aaaa1111-.../resourceGroups/rg-prod'.

The active context is correct, so it is not a tenant mix-up. Listing the SP’s assignments at the scope:

az role assignment list --assignee d4e5f6a7-1111-2222-3333-444455556666 \
  --scope /subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod \
  --include-inherited -o table

Principal                              Role          Scope
-------------------------------------  ------------  --------------------------------------------------
d4e5f6a7-1111-2222-3333-444455556666   Contributor   /subscriptions/aaaa1111-.../resourceGroups/rg-prod

Contributor clearly includes VM write, so a missing assignment is not the cause. Checking for a deny assignment:

az rest --method get \
  --url "https://management.azure.com/subscriptions/aaaa1111-bbbb-cccc-dddd-eeee22223333/resourceGroups/rg-prod/providers/Microsoft.Authorization/denyAssignments?api-version=2022-04-01" \
  --query "value[].{name:properties.denyAssignmentName, actions:properties.permissions[0].actions}"

[
  {
    "name": "lockdown-compute-writes",
    "actions": [ "Microsoft.Compute/virtualMachines/write" ]
  }
]

A deny assignment named lockdown-compute-writes — pushed by a recently applied Blueprint — blocks all compute writes in rg-prod. Deny beats Contributor, so the SP is rejected.

Fix: exclude the pipeline SP from the deny assignment (or move the build target out of the locked resource group), then re-run the deploy. The VM creates and the pipeline goes green.

Prevention Best Practices

• Grant roles at the narrowest scope that actually covers the work, and prefer built-in roles whose actions you can verify with az role definition list. Most AuthorizationFailed cases are a role assigned one scope too low.
• Audit deny assignments and deny-effect policies before locking a resource group, and explicitly exclude automation principals so pipelines do not silently break.
• After any role change, wait for propagation and force a fresh token (az account clear/re-login) before declaring it broken — stale tokens cause false negatives.
• Pin the active subscription and tenant at the top of every pipeline (az account set --subscription ...) so a default context never sends a write to the wrong scope.
• Keep custom roles minimal but complete: confirm the exact action/dataAction with az provider operation show so the role grants precisely what the workload calls.
• For ad-hoc triage, the free incident assistant can turn an AuthorizationFailed message into the likely scope/role gap. More walkthroughs live in the Azure guides.

Quick Command Reference

# Who am I and where am I pointed?
az account show --query "{sub:name, subId:id, tenant:tenantId, user:user.name}" -o json
az account list -o table

# Effective role assignments at the failing scope
az role assignment list --assignee <OBJECT_ID> --scope <SCOPE> --include-inherited --include-groups -o table
az role assignment list --assignee <OBJECT_ID> --all -o table

# What does the role actually permit?
az role definition list --name "<ROLE_NAME>" --query "[0].permissions[0]" -o json
az provider operation show --namespace <NAMESPACE> -o json

# Deny assignments and policy
az rest --method get --url "https://management.azure.com<SCOPE>/providers/Microsoft.Authorization/denyAssignments?api-version=2022-04-01"
az policy state list --resource <SCOPE> --filter "complianceState eq 'NonCompliant'" -o table

# Fix context / refresh token, then retry
az account set --subscription <SUB_ID>
az account clear && az login

Conclusion

An AuthorizationFailed means RBAC found no grant (or found a deny) for a specific action over a specific scope for a specific principal. The usual root causes:

1. No role assignment grants the requested action at this scope.
2. The role is assigned at the wrong scope and does not inherit to the target.
3. A deny assignment overrides every role assignment, including Owner.
4. An Azure Policy deny effect blocks the write (often seen as RequestDisallowedByPolicy).
5. Propagation delay or a stale token hides a grant that is actually present.
6. The CLI is in the wrong subscription or tenant context.
7. A custom role is missing the exact action/dataAction (or lists it under notActions).

Pull the action, scope, and object id straight from the error, then walk assignments → role definition → deny/policy → token. The fix is almost always one mis-scoped assignment, an unnoticed deny, or a context pointed at the wrong subscription.