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.