Apex Azure Rbac

Azure RBAC Skill

Find the minimal built-in Azure role that grants the requested permissions to an identity, then generate the az role assignment create CLI and a Bicep Microsoft.Authorization/roleAssignments snippet. Custom roles only when no built-in fits.

Rules

• Least privilege first — prefer the most narrowly-scoped built-in role that satisfies the permissions; only define a custom role when no built-in fits
• Role assignment scope matters — prefer resource-level or resource-group scope over subscription scope
• Discover roles via mcp_azure-mcp_documentation — invoke with command: "microsoft_docs_search" to query for built-in role definitions before generating any CLI or Bicep
• Verify with az role definition list — cross-check the discovered role against the live Azure RBAC catalogue
• Use guid() in Bicep for Microsoft.Authorization/roleAssignments names so assignments are idempotent across re-deploys; set principalType: 'ServicePrincipal' for managed identities
• Granting roles requires elevated permission — see Prerequisites for Granting Roles below
• Generate before executing — require explicit approval for the exact principal, role and scope; generic role guidance does not confer write permission for role creation or assignment
• Authentication is separate — use canonical auth guidance; Azure RBAC does not grant Microsoft Graph API consent
• Out of scope: deploying resources (use apex-azure-deploy), security audits (use apex-azure-compliance)

Steps

1. Identify the operation — what action does the identity need (read storage, manage keys, deploy resources, etc.)?

2. Search Microsoft docs — invoke mcp_azure-mcp_documentation with command: "microsoft_docs_search" and a query such as "Azure built-in role <operation>" (e.g., "Azure built-in role read blob storage"); collect candidate role names + role IDs

3. Verify against the live catalogue — preserve every permission block and scope:

   az role definition list --name "<RoleNameOrId>" --query "[].{name:roleName,id:name,permissions:permissions,assignableScopes:assignableScopes}" --output json

   Evaluate all permissions[]: actions minus notActions for management-plane operations, and dataActions minus notDataActions for data-plane operations, with wildcard matching against the requested provider operation. Combine grants across blocks and applicable assignments; exclusions subtract only from their own grant, not other roles. Management */read does not grant blob/secret data access. Check assignment scope/inheritance, conditions, deny assignments and active PIM state separately. A role definition alone does not prove effective access. Missing permissions or unavailable catalogue evidence means unverified, not granted.

4. If no built-in fits — scaffold a custom role definition with only the required actions / dataActions:

   Use editing tools to create custom-role.json; generate the command separately.

   {
     "Name": "<CustomRoleName>",
     "Description": "<purpose>",
     "Actions": ["<provider>/<resource>/<action>"],
     "NotActions": [],
     "DataActions": [],
     "NotDataActions": [],
     "AssignableScopes": ["/subscriptions/<sub-id>"]
   }

   az role definition create --role-definition custom-role.json

5. Generate the assignment CLI —

   az role assignment create \
     --assignee <objectId|appId> \
     --role "<RoleName>" \
     --scope <scope>

6. Generate the IaC snippet —

   Bicep (AVM, preferred): AVM resource modules accept a roleAssignments array, so assign the role where the module deploys the resource. Pin the module version per AVM modules.

   module storage 'br/public:avm/res/storage/storage-account:<version>' = {
     name: 'storage'
     params: {
       name: storageAccountName
       roleAssignments: [
         {
           principalId: principalId
           roleDefinitionIdOrName: 'Storage Blob Data Reader'
           principalType: 'ServicePrincipal'
         }
       ]
     }
   }

   Bicep (raw resource on an existing target):

   param principalId string
   param roleDefinitionGuid string
   param storageAccountName string
   
   resource targetResource 'Microsoft.Storage/storageAccounts@2026-04-01' existing = {
     name: storageAccountName
   }
   
   resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
     name: guid(targetResource.id, principalId, roleDefinitionGuid)
     scope: targetResource
     properties: {
       roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionGuid)
       principalId: principalId
       principalType: 'ServicePrincipal'
     }
   }

   Terraform (raw azurerm_role_assignment):

   resource "azurerm_role_assignment" "this" {
     scope                = azurerm_resource_group.target.id   # or any resource ID
     role_definition_name = "<RoleName>"                       # e.g., "Storage Blob Data Reader"
     principal_id         = azurerm_user_assigned_identity.app.principal_id
     principal_type       = "ServicePrincipal"
     # For idempotent imports/refreshes, lock to the role definition GUID instead:
     # role_definition_id = "/subscriptions/${data.azurerm_subscription.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/<role-id-guid>"
   }

   AVM-TF callers should prefer the Azure/avm-res-authorization-roleassignment module over raw azurerm_role_assignment when available — it wraps the resource with the canonical AVM input/output contract.

7. Verify the caller has assignment permission — cross-check with Prerequisites for Granting Roles