# Role Definition

Source: /azure/services/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?](https://learn.microsoft.com/en-us/azure/role-based-access-control/overview).

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](#api-coverage), 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](/azure/getting-started/). Once the container is running, enable Azure CLI interception by running:

```bash
lstk az 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:

```bash
lstk az 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`](https://learn.microsoft.com/en-us/cli/azure/role/definition#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:

```bash
az role definition list --output table
```

```bash title="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`:

```json title="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:

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

```bash title="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](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles-cli#list-a-custom-role-definition):

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

```bash title="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](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles-cli), retrieve the current definition with `az role definition list`, edit the JSON (for example permissions or assignable scopes), then apply the update:

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

### Delete a custom role definition

Delete the custom role definition by name:

```bash
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 enforcement is opt-in:** By default, role definitions and assignments are stored but permissions are not enforced, so API calls are not gated the way they are in Azure. Set `LS_AZURE_ENFORCE_RBAC` to enable enforcement; see [Role Assignment: Enabling RBAC enforcement](/azure/services/role-assignment/#enabling-rbac-enforcement) for scope and coverage.
- **Management group scopes:** Management group–level assignable scopes are not supported.

## Samples

Explore end-to-end examples in the [LocalStack for Azure Samples](https://github.com/localstack/localstack-azure-samples) repository.

## API Coverage


### Role Definition API coverage

Source service: `role-definition`. 4 of 4 tracked operations are implemented.

Service documentation: /azure/services/role-definition/

| Operation | Status |
| --- | --- |
| RoleDefinitions.CreateOrUpdate | Implemented |
| RoleDefinitions.Delete | Implemented |
| RoleDefinitions.Get | Implemented |
| RoleDefinitions.List | Implemented |