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 role definitions

Run az role definition list to list role definitions for the current subscription. The results include built-in roles (such as Owner, Contributor, and Reader) as well as any custom roles:

az role definition list --output table

Output

Name                                     Type                                     Description
---------------------------------------  ---------------------------------------  -----------------------------------------------------------
Contributor                              Microsoft.Authorization/roleDefinitions  Grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC...
Owner                                    Microsoft.Authorization/roleDefinitions  Grants full access to manage all resources, including assigning roles in Azure RBAC...
Reader                                   Microsoft.Authorization/roleDefinitions  View all resources, but does not allow you to make any 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"
  ],
  "NotActions": [],
  "DataActions": [
    "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
  ],
  "NotDataActions": [],
  "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"],
  "description": "Can read storage blobs.",
  "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"
      ],
      "notActions": [],
      "dataActions": [
        "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
      ],
      "notDataActions": []
    }
  ],
  "roleName": "Custom Storage Reader",
  "roleType": "CustomRole",
  "type": "Microsoft.Authorization/roleDefinitions"
...
}

List a role definition by name

List role definitions that match the display name (roleName), as in Azure’s custom role CLI workflow:

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

Output

[
  {
    "assignableScopes": ["/subscriptions/00000000-0000-0000-0000-000000000000"],
    "description": "Can read storage blobs.",
    "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"
        ],
        "notActions": [],
        "dataActions": [
          "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
        ],
        "notDataActions": []
      }
    ],
    "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. As described in Create or update Azure custom roles using Azure CLI, retrieve the current definition with az role definition list, edit the JSON (for example permissions or assignable scopes), then apply the update:

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 permissions are not enforced: API calls are not gated the way they are in Azure, and effective access for a principal at a scope is not evaluated from assignments and role definitions.
• 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