Custom role definitions in Azure - Deep Dive

Overview - Custom role definitions

What is it?

Custom role definitions in Azure let you create your own sets of permissions to control access to resources. Instead of using built-in roles, you define exactly what actions are allowed or denied. This helps tailor security to your organization's specific needs. It works by specifying permissions in a JSON format that Azure understands.

Why it matters

Without custom roles, you must rely on broad built-in roles that might give too much or too little access. This can lead to security risks or operational problems. Custom roles solve this by letting you grant just the right permissions, improving security and efficiency. This means fewer mistakes and better control over who can do what in your cloud environment.

Where it fits

Before learning custom role definitions, you should understand Azure role-based access control (RBAC) basics and built-in roles. After mastering custom roles, you can explore advanced access management like conditional access policies and identity governance. This topic fits in the journey of securing and managing Azure resources effectively.

Mental Model

Core Idea

A custom role definition is a precise permission recipe that tells Azure exactly what actions a user or group can perform on resources.

Think of it like...

Imagine a custom role as a personalized keyring where you pick only the keys needed to open certain doors, instead of carrying a big master key that opens everything.

┌───────────────────────────────┐
│       Custom Role Definition   │
├───────────────┬───────────────┤
│ Permissions   │ Actions       │
│               │ - Read        │
│               │ - Write       │
│               │ - Delete      │
├───────────────┴───────────────┤
│ Assignable Scopes (where it applies) │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Azure RBAC Basics

Concept: Learn what role-based access control (RBAC) is and how it manages permissions in Azure.

Azure RBAC controls who can access Azure resources and what they can do. It uses roles that group permissions. Built-in roles like Owner, Contributor, and Reader come predefined. These roles are assigned to users, groups, or service principals at different scopes like subscriptions or resource groups.

Result

You understand how Azure controls access using roles and scopes.

Knowing RBAC basics is essential because custom roles build on this system to provide tailored permissions.

2

Foundation

Exploring Built-in Roles Limitations

Concept: See why built-in roles might not fit all scenarios and why custom roles are needed.

Built-in roles cover common permission sets but can be too broad or too narrow. For example, the Contributor role allows managing all resources but not assigning roles. Sometimes you need a role that allows only specific actions, like starting virtual machines but not deleting them.

Result

You recognize scenarios where built-in roles are insufficient.

Understanding built-in roles' limits helps you appreciate the need for custom roles to tighten security.

3

Intermediate

Creating a Custom Role Definition JSON

🤔Before reading on: do you think a custom role JSON only lists allowed actions or also includes denied actions? Commit to your answer.

Concept: Learn the structure of a custom role definition in JSON format.

A custom role JSON includes: 'Name' (role name), 'Description', 'Actions' (allowed operations), 'NotActions' (denied operations), 'AssignableScopes' (where the role applies). Actions use Azure resource provider operations like 'Microsoft.Compute/virtualMachines/start/action'. NotActions exclude specific permissions from allowed actions.

Result

You can write a valid JSON defining a custom role with precise permissions.

Knowing the JSON structure lets you customize permissions exactly, improving security and flexibility.

4

Intermediate

Assigning Custom Roles to Users

🤔Before reading on: do you think custom roles can be assigned at any scope like subscriptions, resource groups, or individual resources? Commit to your answer.

Concept: Understand how to assign your custom role to users or groups at different scopes.

After creating a custom role, assign it to a user, group, or service principal using Azure Portal, CLI, or PowerShell. You specify the scope such as subscription, resource group, or resource. The assigned user then gets the permissions defined in the custom role only within that scope.

Result

Users gain tailored permissions limited to the assigned scope.

Assigning roles at the right scope prevents over-permission and enforces least privilege.

5

Advanced

Using NotActions to Deny Specific Permissions

🤔Before reading on: do you think NotActions can override Actions to deny permissions even if they are included? Commit to your answer.

Concept: Learn how to exclude specific permissions from allowed actions using NotActions.

NotActions lets you remove certain permissions from the allowed Actions list. For example, you can allow all Contributor permissions but deny deleting resources by listing delete actions in NotActions. This creates a more precise permission set without listing every allowed action individually.

Result

You can create custom roles that allow broad permissions but block sensitive actions.

Using NotActions helps avoid mistakes and reduces the complexity of permission lists.

6

Advanced

Versioning and Updating Custom Roles Safely

🤔Before reading on: do you think updating a custom role immediately changes permissions for all assigned users or requires re-assignment? Commit to your answer.

Concept: Understand how to update custom roles and manage changes without disrupting access.

Custom roles can be updated by modifying their JSON and re-uploading. Changes take effect immediately for all users assigned that role. To avoid accidental permission loss, use version control and test changes in a non-production environment first. Azure does not support role versioning natively, so manual tracking is needed.

Result

You can safely evolve custom roles while minimizing risk.

Knowing update behavior prevents unexpected access issues in production.

7

Expert

Advanced Scoping and Inheritance in Custom Roles

🤔Before reading on: do you think assigning a custom role at a subscription scope automatically grants permissions to all resources inside it? Commit to your answer.

Concept: Explore how scope assignment affects permission inheritance and how to combine scopes for complex needs.

Assigning a custom role at a higher scope like subscription grants permissions to all child resources unless overridden. You can assign the same role at multiple scopes for different users. Understanding scope hierarchy and inheritance helps design least privilege access. Azure evaluates the most permissive role across all assignments for a user.

Result

You can design complex access models using scope inheritance and multiple assignments.

Mastering scope inheritance avoids permission leaks and enforces precise access control.

Under the Hood

Azure stores custom role definitions as JSON objects in its control plane. When a user requests access, Azure evaluates all role assignments at relevant scopes. It merges permissions from built-in and custom roles, applying Actions and NotActions to determine allowed operations. This evaluation happens in real time during resource access requests.

Why designed this way?

Azure designed custom roles to provide flexibility beyond fixed built-in roles. JSON format was chosen for its simplicity and compatibility with APIs and automation tools. The Actions/NotActions model balances ease of use with fine-grained control. Scope-based assignments align with Azure's hierarchical resource model for scalable access management.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Custom Role   │──────▶│ Role Assignment│──────▶│ User/Group    │
│ Definition    │       │ at Scope       │       │ Permissions   │
└───────────────┘       └───────────────┘       └───────────────┘
         │                      │                      ▲
         │                      │                      │
         ▼                      ▼                      │
┌───────────────────────────────────────────────────────────┐
│ Azure Access Evaluation Engine                             │
│ - Merges all roles assigned to user at scopes            │
│ - Applies Actions and NotActions to allow or deny access  │
└───────────────────────────────────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think custom roles can deny permissions explicitly like a firewall blocks traffic? Commit to yes or no.

Common Belief: Custom roles can explicitly deny permissions to block actions.

Reality: Custom roles cannot explicitly deny permissions; they only allow actions listed in 'Actions' and exclude those in 'NotActions'. Anything not allowed is implicitly denied.

Why it matters: Believing in explicit deny can cause security gaps if you assume some actions are blocked when they are not.

Quick: Do you think updating a custom role requires reassigning it to users? Commit to yes or no.

Common Belief: You must reassign a custom role after updating its permissions for changes to take effect.

Reality: Updates to a custom role apply immediately to all users assigned that role without needing reassignment.

Why it matters: Misunderstanding this can lead to confusion about permission changes and delays in applying security fixes.

Quick: Do you think assigning a custom role at a resource group scope grants permissions to all resources inside it? Commit to yes or no.

Common Belief: Assigning a role at a resource group scope automatically applies permissions to all resources within that group.

Reality: Yes, role assignments at a scope apply to all child resources unless overridden by more specific assignments.

Why it matters: Incorrectly assigning roles at broad scopes can unintentionally grant excessive permissions.

Quick: Do you think NotActions can add permissions not listed in Actions? Commit to yes or no.

Common Belief: NotActions can add permissions beyond those listed in Actions.

Reality: NotActions only remove permissions from those allowed by Actions; they cannot add permissions.

Why it matters: Misusing NotActions can cause roles to lack needed permissions, breaking workflows.

Expert Zone

1

Custom roles must be carefully tested because missing a single required action can cause subtle failures in resource management.

2

Azure evaluates all role assignments for a user and grants the union of permissions, so overlapping roles can unintentionally increase access.

3

The JSON schema for custom roles evolves; using the latest schema version ensures compatibility and access to new features.

When NOT to use

Avoid custom roles when built-in roles fully meet your needs, as custom roles add management overhead. For dynamic or conditional access, use Azure AD Conditional Access policies or Privileged Identity Management instead.

Production Patterns

In production, custom roles are often used to create least privilege roles for automation accounts, developers, or auditors. Teams maintain role definitions in source control and deploy them via automation pipelines to ensure consistency and auditability.

Connections

Least Privilege Security Principle

Custom roles implement least privilege by granting only necessary permissions.

Understanding least privilege helps design custom roles that minimize risk by limiting access to just what is needed.

JSON Data Format

Custom roles are defined using JSON, a widely used data format for configuration.

Knowing JSON basics enables easier creation and modification of custom role definitions.

Access Control Lists (ACLs) in Operating Systems

Both custom roles and ACLs control who can do what to resources, using permission sets.

Recognizing this similarity helps understand access control concepts across computing domains.

Common Pitfalls

#1 Granting too many permissions by assigning custom roles at broad scopes.

Wrong approach:

Assign-AzRoleAssignment -ObjectId user1 -RoleDefinitionName 'CustomRole' -Scope /subscriptions/12345678

Correct approach:

Assign-AzRoleAssignment -ObjectId user1 -RoleDefinitionName 'CustomRole' -Scope /subscriptions/12345678/resourceGroups/myResourceGroup

Root cause:

Misunderstanding scope hierarchy leads to over-permission by assigning roles at subscription instead of resource group level.

#2 Defining a custom role JSON without specifying 'AssignableScopes'.

Wrong approach:

{ "Name": "MyRole", "Actions": ["Microsoft.Compute/virtualMachines/start/action"] }

Correct approach:

{ "Name": "MyRole", "Actions": ["Microsoft.Compute/virtualMachines/start/action"], "AssignableScopes": ["/subscriptions/12345678"] }

Root cause:

Forgetting 'AssignableScopes' causes the role to be invalid and not assignable.

#3 Using NotActions to try to add permissions not listed in Actions.

Wrong approach:

"Actions": ["Microsoft.Storage/*"], "NotActions": ["Microsoft.Storage/delete"]

Correct approach:

"Actions": ["Microsoft.Storage/*"], "NotActions": ["Microsoft.Storage/delete"]

Root cause:

Misunderstanding that NotActions only removes permissions; it cannot add permissions beyond Actions.

Key Takeaways

Custom role definitions let you tailor Azure permissions precisely to your needs using JSON.

They build on Azure RBAC by allowing you to specify allowed and excluded actions at defined scopes.

Understanding scope hierarchy and permission evaluation is key to avoiding over-permission.

Custom roles improve security by enforcing least privilege but require careful design and testing.

Updates to custom roles apply immediately, so manage changes carefully to prevent access issues.