Role Definition

Introduction

Azure Role Definitions are the building blocks of Azure role-based access control (RBAC). A role definition is a collection of permissions that can be assigned to identities at a specific scope. They allow organizations to grant least-privilege access to Azure resources by defining precisely which operations an identity is permitted to perform. For more information, see What is Azure RBAC?.

LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Role Definitions. The supported APIs are available on our API Coverage section, which provides information on the extent of Role Definitions’ integration with LocalStack.

Getting started

This guide walks you through creating a custom role definition, listing role definitions, and deleting the custom role.

Launch LocalStack using your preferred method. For more information, see Introduction to LocalStack for Azure. Once the container is running, enable Azure CLI interception by running:

azlocal start-interception

This command points the az CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API. To revert this configuration, run:

azlocal stop-interception

This reconfigures the az CLI to send commands to the official Azure management REST API.

List built-in role definitions

List all built-in Azure role definitions available in the current subscription:

az role definition list --output table

Output

Name                                     Type                                     Description
---------------------------------------  ---------------------------------------  -----------------------------------------------------------
Contributor                              Microsoft.Authorization/roleDefinitions  Grants full access to manage all resources...
Owner                                    Microsoft.Authorization/roleDefinitions  Grants full access to manage all resources...
Reader                                   Microsoft.Authorization/roleDefinitions  View all resources, but does not allow you to make changes.
...

Create a custom role definition

Save the following JSON to custom-role.json:

custom-role.json

{
  "Name": "Custom Storage Reader",
  "Description": "Can read storage blobs.",
  "Actions": [
    "Microsoft.Storage/storageAccounts/blobServices/containers/read",
    "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
  ],
  "NotActions": [],
  "AssignableScopes": [
    "/subscriptions/00000000-0000-0000-0000-000000000000"
  ]
}

Then create the role:

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

Output

{
  "assignableScopes": ["/subscriptions/00000000-0000-0000-0000-000000000000"],
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/blobServices/containers/read",
        "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
      ],
      "notActions": []
    }
  ],
  "roleName": "Custom Storage Reader",
  "roleType": "CustomRole",
  "type": "Microsoft.Authorization/roleDefinitions"
...
}

List role definitions

List all role definitions that match the custom role name:

az role definition list --name "Custom Storage Reader"

Output

[
  {
    "assignableScopes": ["/subscriptions/00000000-0000-0000-0000-000000000000"],
    "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/storageAccounts/blobServices/containers/read",
          "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
        ],
        "notActions": []
      }
    ],
    "roleName": "Custom Storage Reader",
    "roleType": "CustomRole",
    "type": "Microsoft.Authorization/roleDefinitions"
  }
]

Update a custom role definition

Update the custom role definition by passing a modified JSON definition file:

az role definition update --role-definition @custom-role.json

Delete a custom role definition

Delete the custom role definition by name:

az role definition delete --name "Custom Storage Reader"
az role definition list --name "Custom Storage Reader"

Features

• Custom role creation: Create custom role definitions with Actions, NotActions, DataActions, and NotDataActions.
• Built-in roles pre-populated: Standard Azure built-in roles are available via az role definition list.
• Role listing and filtering: List role definitions by name, scope, or custom flag.
• Role update: Update existing custom role definitions including permissions and assignable scopes.
• Role deletion: Delete custom role definitions by name or ID.
• Assignable scopes support: Roles specify assignable scopes at subscription or resource group level.

Limitations

• RBAC not enforced: Role definitions and assignments are stored in the emulator but are not enforced. All API calls succeed regardless of whether the caller has the required permissions.
• No built-in role permission evaluation: Checking effective permissions via az role assignment list-access is not supported.
• Management group scopes: Management group–level assignable scopes are not supported.

Samples

Explore end-to-end examples in the LocalStack for Azure Samples repository.

API Coverage

Operation ▲	Implemented ▼

PreviousPage 1 of 0Next