Azure Role Streamlined

Find the minimal Azure RBAC role for a set of permissions and generate CLI commands plus Bicep snippets for assignment.

When to Use This Command

Run this command when you need to:

• Identify the least-privilege built-in Azure role that grants specific permissions to an identity
• Generate az role assignment CLI commands ready to execute for role binding
• Produce Bicep infrastructure-as-code snippets for reproducible role assignments

Consider alternatives when:

• You need to manage Entra ID (Azure AD) application roles rather than Azure RBAC roles
• You want to audit existing role assignments across a subscription (use az role assignment list)

Quick Start

Configuration

Copy
name: azure-role-streamlined
type: command
category: azure

Example Invocation

Copy
claude command:run azure-role-streamlined --permissions "Microsoft.Storage/storageAccounts/read,Microsoft.Storage/storageAccounts/listKeys/action" --identity [email protected]

Example Output

[Role Lookup] Searching built-in roles for requested permissions...
[Match] Storage Account Key Operator Service Role
  - Covers: storageAccounts/read, storageAccounts/listKeys/action
  - Role ID: 81a9662b-bebf-436f-a333-f67b29880f12
  - Extra permissions: 2 (minimal overshoot)

[CLI Command]
az role assignment create \
  --assignee [email protected] \
  --role "Storage Account Key Operator Service Role" \
  --scope /subscriptions/{sub-id}/resourceGroups/{rg}

[Bicep Snippet]
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, 'storage-key-operator')
  properties: {
    principalId: '{principal-object-id}'
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '81a9662b-bebf-436f-a333-f67b29880f12')
  }
}

Core Concepts

Role Selection Overview

Aspect	Details
Strategy	Least-privilege: find the narrowest built-in role covering all requested permissions
Fallback	If no built-in role matches, generate a custom role definition JSON
Scope Levels	Management group, subscription, resource group, or individual resource
Output Formats	Azure CLI commands and Bicep infrastructure-as-code snippets

Role Resolution Workflow

[List Required Permissions]
         |
[Search Built-in Roles] --> Match all permissions?
    /          \
  Yes           No
   |             |
[Select Role]  [Generate Custom Role JSON]
   |             |
[Generate CLI + Bicep]
         |
[Apply at Correct Scope]

Configuration

Parameter	Type	Default	Description
permissions	string	required	Comma-separated Azure permission strings to match
identity	string	required	User principal, service principal, or managed identity to assign
scope	string	subscription	Scope for the assignment (subscription, resource group, or resource ID)
custom-role	boolean	false	Force creation of a custom role even if a built-in role matches
output	string	both	Output format: cli, bicep, or both

Best Practices

1. Always Use Least Privilege - Start with the minimum permissions your workload requires and expand only when a specific operation fails. Over-permissioned identities are a top cloud security risk.

2. Scope Assignments Narrowly - Assign roles at the resource or resource group level rather than subscription level. Broad scopes grant access to resources the identity does not need.

3. Prefer Built-in Roles - Custom roles add maintenance overhead and can drift from Azure platform updates. Use built-in roles whenever they cover your requirements, even with minor extra permissions.

4. Use Bicep for Production - CLI commands are useful for quick testing, but production role assignments should be managed as Bicep or ARM templates in version control for auditability and reproducibility.

5. Document Permission Rationale - Add comments to your Bicep templates explaining why each role was chosen and what operations it enables. This helps during security reviews and audits.

Common Issues

1. Role Assignment Propagation Delay - Azure RBAC changes can take up to 10 minutes to propagate. If an identity gets a 403 immediately after assignment, wait and retry before troubleshooting further.

2. Duplicate Role Assignments - Assigning the same role at the same scope twice is idempotent but generates confusing audit logs. Check existing assignments with az role assignment list before creating new ones.

3. Custom Role Limit Reached - Azure subscriptions have a limit of 5,000 custom roles. If you hit this ceiling, consolidate overlapping custom roles or switch to built-in alternatives.