Azure Rbac Diagnostics

Azure RBAC Diagnostics

A playbook for "it's a permissions error" situations on Azure. The goal is to output a precise diagnosis and a remediation command — not just "check your permissions".

1. Identify what failed

From the error message, extract:

• The operation that failed (e.g., Microsoft.Authorization/roleAssignments/write,

a Key Vault secret read, an ACR pull/push, an ADX query/ingest).

• The scope (resource ID / resource group / subscription) the operation targeted.
• The principal that attempted it — may be a user, a CI service principal

(check ARM_CLIENT_ID / pipeline variables), or a managed identity (check the resource's identity block in Terraform).

2. Check current state with az CLI

# Who am I / what's the active identity?
az account show

# What roles does the principal already have at/above the target scope?
az role assignment list --assignee  --all -o table

# What role assignments exist at the target scope (regardless of assignee)?
az role assignment list --scope  -o table

# Resolve a service principal's object ID from its client/app ID if needed
az ad sp show --id  --query id -o tsv

3. Classify the failure

a) Executing identity lacks a sufficiently privileged role

• Most common for Terraform CI service principals trying to create

azurerm_role_assignment resources: this requires User Access Administrator (or Owner) on the target scope, which a plain Contributor does not have.

• This is not a code bug. The Terraform/code is correct; the gap is purely

in the Azure RBAC assignments for the deployer's own identity.

• Output: the exact missing assignment, expressed as a ready-to-run command for

whoever has Owner/User Access Administrator: ``bash az role assignment create \ --assignee \ --role "User Access Administrator" \ --scope /subscriptions//resourceGroups/ ``

• Tell the user this step requires a human with elevated privileges (an Azure

Owner / subscription admin) — it cannot be self-granted by the blocked identity.

b) Target identity (managed identity / app) lacks data-plane access

• E.g., Function App's managed identity needs Key Vault Secrets User, ADX needs

a database Viewer/Admin principal assignment, ACR needs AcrPull/AcrPush.

• Check whether Terraform already defines this role assignment — if yes, this is

likely the same "deployer can't create role assignments" issue (case a) blocking this assignment from ever being created. If no, it's a real missing-config bug: add the azurerm_role_assignment (or equivalent) resource.

c) Wrong principal/scope referenced in code

• The role assignment exists/was created but points at the wrong object ID, or the

scope is too narrow/broad. This is a real bug — fix the .tf/config and re-apply.

4. After remediation

• Once an admin grants the missing role, re-run the failed operation

(terraform plan/apply, app restart, etc.) — propagation can take a minute or two for new role assignments.

• If a resource was created out-of-band while troubleshooting, it may now need an

import {} block — see the terraform-plan-review skill.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sergeyitaly
• Source: sergeyitaly/claude-skill-deployer
• License: MIT

Install and usage instructions live in the source repository linked above.