Custom role definitions in Azure - Commands & Configuration

Introduction

Sometimes you need to give people just the right permissions in Azure, not too many and not too few. Custom role definitions let you create your own permission sets tailored to your needs.

When you want to allow a user to manage only virtual machines but not storage accounts.

When you need to give a team permission to read resources but not change them.

When built-in roles are too broad or too narrow for your organization's security rules.

When you want to limit access to specific actions like starting or stopping services.

When you want to create a role for a temporary project with unique permission needs.

Config File - customRoleDefinition.json

customRoleDefinition.json

{
  "Name": "Custom VM Operator",
  "IsCustom": true,
  "Description": "Can start and stop virtual machines but cannot delete them.",
  "Actions": [
    "Microsoft.Compute/virtualMachines/start/action",
    "Microsoft.Compute/virtualMachines/deallocate/action",
    "Microsoft.Compute/virtualMachines/read"
  ],
  "NotActions": [
    "Microsoft.Compute/virtualMachines/delete/action"
  ],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000"
  ]
}

Name: The name of your custom role.
IsCustom: Marks this as a custom role.
Description: Explains what this role can do.
Actions: Lists allowed actions like starting or reading VMs.
NotActions: Lists actions explicitly denied, like deleting VMs.
AssignableScopes: Defines where this role can be assigned, here the whole subscription.

Commands

This command creates the custom role in Azure using the JSON file you prepared.

Terminal

az role definition create --role-definition customRoleDefinition.json

Expected Output

{

  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/11111111-1111-1111-1111-111111111111",

  "name": "11111111-1111-1111-1111-111111111111",

  "properties": {

    "roleName": "Custom VM Operator",

    "description": "Can start and stop virtual machines but cannot delete them.",

    "type": "CustomRole",

    "permissions": [

      {

        "actions": [

          "Microsoft.Compute/virtualMachines/start/action",

          "Microsoft.Compute/virtualMachines/deallocate/action",

          "Microsoft.Compute/virtualMachines/read"

        ],

        "notActions": [

          "Microsoft.Compute/virtualMachines/delete/action"

        ]

      }

    ],

    "assignableScopes": [

      "/subscriptions/00000000-0000-0000-0000-000000000000"

    ]

  }

}

→

--role-definition - Specifies the JSON file with the custom role definition.

This command checks that your custom role was created and shows its details.

Terminal

az role definition list --name "Custom VM Operator"

Expected Output

[{

  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/11111111-1111-1111-1111-111111111111",

  "name": "11111111-1111-1111-1111-111111111111",

  "properties": {

    "roleName": "Custom VM Operator",

    "description": "Can start and stop virtual machines but cannot delete them.",

    "type": "CustomRole",

    "permissions": [

      {

        "actions": [

          "Microsoft.Compute/virtualMachines/start/action",

          "Microsoft.Compute/virtualMachines/deallocate/action",

          "Microsoft.Compute/virtualMachines/read"

        ],

        "notActions": [

          "Microsoft.Compute/virtualMachines/delete/action"

        ]

      }

    ],

    "assignableScopes": [

      "/subscriptions/00000000-0000-0000-0000-000000000000"

    ]

  }

}]

→

--name - Filters the list to show only the custom role by name.

Key Concept

If you remember nothing else from this pattern, remember: custom roles let you give just the right permissions by defining allowed and denied actions in a JSON file.

Common Mistakes

Using incorrect or incomplete action names in the Actions list.

Azure will reject the role definition or the role won't work as expected if actions are wrong.

Always use exact Azure action names from official documentation or existing roles.

Not specifying AssignableScopes or using an invalid scope.

The role cannot be assigned anywhere if the scope is missing or wrong.

Set AssignableScopes to the subscription or resource group where you want to use the role.

Trying to assign the role before it is created.

Azure will not find the role and assignment will fail.

Create the role first with az role definition create, then assign it.

Summary

Create a JSON file defining allowed and denied actions for your custom role.

Use az role definition create to add the custom role to your Azure subscription.

Verify the role exists with az role definition list before assigning it to users.

Practice

1. What is the main purpose of creating a custom role definition in Azure?

easy

A. To tailor permissions exactly to specific needs

B. To delete all existing roles in Azure

C. To automatically assign roles to all users

D. To create virtual machines quickly

Solution

1. Step 1: Understand role customization

   Custom roles allow you to specify exactly which permissions are granted or denied, unlike built-in roles which are fixed.

2. Step 2: Identify the purpose of custom roles

   They help tailor permissions to fit specific needs, improving security and control.

3. Final Answer:

   To tailor permissions exactly to specific needs -> Option A

4. Quick Check:

   Custom roles = tailored permissions [OK]

Hint: Custom roles = tailor permissions to your needs [OK]

Common Mistakes:

• Thinking custom roles delete existing roles
• Assuming custom roles auto-assign to all users
• Confusing custom roles with VM creation

2. Which JSON property is required to specify the permissions allowed in a custom role definition?

easy

A. "NotActions"

B. "Actions"

C. "allowedActions"

D. "permissions"

Solution

1. Step 1: Review custom role JSON structure

   The property "Actions" lists the allowed operations in the role definition.

2. Step 2: Differentiate from other properties

   "NotActions" lists denied permissions, "permissions" is a container but not the direct property, and "allowedActions" is not a valid property.

3. Final Answer:

   "Actions" -> Option B

4. Quick Check:

   Allowed permissions = "Actions" [OK]

Hint: Allowed permissions are under "Actions" in JSON [OK]

Common Mistakes:

• Using "allowedActions" which is invalid
• Confusing "NotActions" with allowed permissions
• Mistaking "permissions" as direct actions list

3. Given this snippet of a custom role JSON:

{
  "Name": "Storage Reader",
  "Actions": ["Microsoft.Storage/storageAccounts/read"],
  "NotActions": []
}

What permission does this role grant?

medium

A. No permissions at all

B. Full control over storage accounts

C. Write access to storage accounts

D. Read access to storage accounts

Solution

1. Step 1: Analyze the "Actions" property

   The action "Microsoft.Storage/storageAccounts/read" grants read-only access to storage accounts.

2. Step 2: Check "NotActions" property

   It is empty, so no permissions are excluded.

3. Final Answer:

   Read access to storage accounts -> Option D

4. Quick Check:

   Action includes "read" = read access [OK]

Hint: Look for "read" in actions for read-only permission [OK]

Common Mistakes:

• Assuming full control from read action
• Confusing read with write permissions
• Ignoring empty NotActions meaning no exclusions

4. You created a custom role but users report they cannot perform allowed actions. Which is the most likely error in the role definition?

medium

A. Role description is missing

B. "Actions" property is missing or empty

C. "NotActions" includes the same actions as "Actions"

D. Role name is too long

Solution

1. Step 1: Understand "NotActions" effect

   "NotActions" excludes permissions even if listed in "Actions".

2. Step 2: Identify conflict in permissions

   If "NotActions" includes the same actions as "Actions", those permissions are denied, causing users to lack access.

3. Final Answer:

   "NotActions" includes the same actions as "Actions" -> Option C

4. Quick Check:

   Conflicting "NotActions" denies permissions [OK]

Hint: "NotActions" overrides "Actions" if overlapping [OK]

Common Mistakes:

• Ignoring "NotActions" effect
• Thinking role name or description affects permissions
• Assuming missing "Actions" is common

5. You want to create a custom role that allows users to start and stop virtual machines but denies deleting them. Which JSON snippet correctly defines this?

hard

A. { "Actions": ["Microsoft.Compute/virtualMachines/*"], "NotActions": ["Microsoft.Compute/virtualMachines/delete"] }

B. { "Actions": ["Microsoft.Compute/virtualMachines/start"], "NotActions": ["Microsoft.Compute/virtualMachines/delete"] }

C. { "Actions": ["Microsoft.Compute/virtualMachines/start", "Microsoft.Compute/virtualMachines/delete"], "NotActions": [] }

D. { "Actions": ["Microsoft.Compute/virtualMachines/delete"], "NotActions": ["Microsoft.Compute/virtualMachines/start"] }

Solution

1. Step 1: Identify required permissions

   Users need to start and stop VMs, so all VM actions except delete are allowed.

2. Step 2: Check each option

   { "Actions": ["Microsoft.Compute/virtualMachines/*"], "NotActions": ["Microsoft.Compute/virtualMachines/delete"] } allows all VM actions with "*" but denies delete explicitly, matching requirements perfectly.

3. Step 3: Eliminate incorrect options

   { "Actions": ["Microsoft.Compute/virtualMachines/start"], "NotActions": ["Microsoft.Compute/virtualMachines/delete"] } misses stop (deallocate) action; { "Actions": ["Microsoft.Compute/virtualMachines/start", "Microsoft.Compute/virtualMachines/delete"], "NotActions": [] } allows delete; { "Actions": ["Microsoft.Compute/virtualMachines/delete"], "NotActions": ["Microsoft.Compute/virtualMachines/start"] } denies start but allows delete.

4. Final Answer:

   { "Actions": ["Microsoft.Compute/virtualMachines/*"], "NotActions": ["Microsoft.Compute/virtualMachines/delete"] } -> Option A

5. Quick Check:

   Allow all except delete = Actions with * and NotActions delete [OK]

Hint: Use wildcard * in Actions and exclude delete in NotActions [OK]

Common Mistakes:

• Missing stop (deallocate) action
• Allowing delete action by mistake
• Denying start action instead of delete