🚨 Bicep Error: 'AuthorizationFailed — client does not have authorization to perform action over scope' — Cause, Fix, and Troubleshooting Guide

Overview

AuthorizationFailed is a deploy-time error, not a compile error. Your Bicep file built cleanly into ARM JSON and Azure Resource Manager accepted the template — but when it tried to create or modify a resource, the identity running the deployment lacked the Azure RBAC permission for that specific action at that specific scope. This is an authorization failure, distinct from an authentication failure (bad or expired credentials, which show as InvalidAuthenticationToken).

The error looks like this:

Deployment failed. Correlation ID: 11111111-2222-3333-4444-555555555555. The client 'deployer@example.com' with object id 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' does not have authorization to perform action 'Microsoft.Storage/storageAccounts/write' over scope '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg/providers/Microsoft.Storage/storageAccounts/examplestor' or the scope is invalid. If access was recently granted, please refresh your credentials.

Everything you need is in the message: the identity (object id), the action it needs (Microsoft.Storage/storageAccounts/write), and the scope it needs it on. The fix is always some form of “grant a role that includes that action, at or above that scope, to that identity.” The trailing hint “If access was recently granted, please refresh your credentials” matters — RBAC changes can take a few minutes to propagate and tokens may need refreshing.

Symptoms

• az deployment group create (or a pipeline/service principal deploy) fails with AuthorizationFailed and a Correlation ID.
• The message names an action (like .../write, .../read, or Microsoft.Authorization/roleAssignments/write) and a scope.
• The deployment worked for you locally (Owner) but fails in CI under a service principal or managed identity.
• Some resources in the template deploy; the first one hitting a missing permission fails and rolls back.
• Deploying a role assignment or Key Vault access itself fails — because assigning roles requires Microsoft.Authorization/roleAssignments/write.

Common Root Causes

1. Service principal / managed identity has no role at the target scope

The most common CI cause: the pipeline’s SP was created but never granted a role on the resource group or subscription it deploys to.

action: Microsoft.Storage/storageAccounts/write
scope:  /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg

2. Role assigned at too narrow a scope

The identity has Contributor on resourceGroupA but the template targets resourceGroupB, or a resource whose parent is outside the assigned scope.

3. Template creates role assignments without Owner/User Access Administrator

Creating an Microsoft.Authorization/roleAssignments resource (common for granting a managed identity access to Key Vault) requires elevated rights. Contributor cannot assign roles.

action: Microsoft.Authorization/roleAssignments/write

4. Deployment scope mismatch

A subscription-scoped or managementGroup-scoped Bicep deployment (using targetScope) needs the identity to have a role at that higher scope, not just on one resource group.

targetScope = 'subscription'   // identity now needs subscription-level rights

5. Custom role missing the required action

A least-privilege custom role that omits the exact action string (or does not cover a dataActions operation) fails on that operation even though it looks “mostly” sufficient.

6. Recent grant not yet propagated / stale token

The role was just assigned but Azure AD/ARM has not propagated it, or the cached token predates the grant.

How to Diagnose

Step 1: Identify who is actually deploying

az account show --query user
az ad signed-in-user show --query id -o tsv     # for a user
# For a service principal in CI, the object id is in the error message.

Match this object id against the one in the AuthorizationFailed message.

Step 2: List the identity’s role assignments at the scope

az role assignment list \
  --assignee aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg \
  --include-inherited \
  --output table

If the list is empty (or only shows Reader), that is your answer.

Step 3: Confirm which action and scope failed

Read them straight from the error, or pull the deployment operation detail:

az deployment operation group list \
  --resource-group example-rg \
  --name <deploymentName> \
  --query "[?properties.provisioningState=='Failed'].properties.statusMessage"

Step 4: Verify a role definition actually contains the action

az role definition list --name "Contributor" \
  --query "[0].permissions[0].actions" -o tsv | tr ',' '\n' | grep -i storage

Fixes

Grant a built-in role at the correct scope

For a service principal that needs to create resources in a resource group, Contributor is usually right:

az role assignment create \
  --assignee aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --role "Contributor" \
  --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg

Grant role-assignment rights for templates that assign roles

If the template creates roleAssignments, the deployer needs Owner or User Access Administrator (or a custom role including Microsoft.Authorization/roleAssignments/write):

az role assignment create \
  --assignee aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --role "User Access Administrator" \
  --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/example-rg

Match the role scope to the deployment scope

For a subscription-scoped Bicep deployment, assign at the subscription:

az role assignment create \
  --assignee aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --role "Contributor" \
  --scope /subscriptions/00000000-0000-0000-0000-000000000000

Add the missing action to a custom role

az role definition update --role-definition @custom-deployer-role.json

Ensure the exact action string from the error appears in the role’s actions (or dataActions) array.

Refresh credentials and wait for propagation

After granting, re-login so the new token carries the assignment, then retry:

az logout && az login
# For SPs, request a fresh token; allow a few minutes for RBAC to propagate.
az deployment group create --resource-group example-rg --template-file main.bicep

What to Watch Out For

• Read the three facts from the error — identity object id, action, scope — and fix exactly those; do not over-grant.
• Assigning roles is privileged: any template that creates roleAssignments needs Owner or User Access Administrator, not plain Contributor.
• The RBAC scope must be at or above the deployment’s targetScope; a resource-group role cannot satisfy a subscription-scoped deployment.
• Prefer least privilege, but verify a custom role literally contains the failing action string before blaming propagation.
• After granting a role, allow a few minutes and refresh tokens — the “recently granted” hint is real, not boilerplate.
• Authentication (InvalidAuthenticationToken) and authorization (AuthorizationFailed) are different failures — confirm you are solving the right one.
• In CI, store the SP’s object id and its assigned scopes somewhere reviewable so permission drift is easy to audit.

Related Guides

• Bicep InvalidTemplate & BCP Compile Errors
• Managing Secrets in Infrastructure as Code
• Detecting and Fixing Infrastructure Config Drift