Skip to content

Commit bc73c8c

Browse files
paolosalvatoriremotesynth
paolosalvatori
and
remotesynth
authored
Azure Docs: Azure Role Definition (#591)
Co-authored-by: Brian Rinaldi <brian.rinaldi@gmail.com>
1 parent 7e496a9 commit bc73c8c

1 file changed

Lines changed: 178 additions & 0 deletions

File tree

‎src/content/docs/azure/services/role-definition.mdx‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
title: "Role Definition"
3+
description: Get started with Azure Role Definitions on LocalStack
4+
template: doc
5+
---
6+
7+
import AzureFeatureCoverage from "../../../../components/feature-coverage/AzureFeatureCoverage";
8+
9+
## Introduction
10+
11+
Azure Role Definitions are the building blocks of Azure role-based access control (RBAC).
12+
A role definition is a collection of permissions that can be assigned to identities at a specific scope.
13+
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).
14+
15+
LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Role Definitions.
16+
The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of Role Definitions' integration with LocalStack.
17+
18+
## Getting started
19+
20+
This guide walks you through creating a custom role definition, listing role definitions, and deleting the custom role.
21+
22+
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:
23+
24+
```bash
25+
azlocal start-interception
26+
```
27+
28+
This command points the `az` CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API.
29+
To revert this configuration, run:
30+
31+
```bash
32+
azlocal stop-interception
33+
```
34+
35+
This reconfigures the `az` CLI to send commands to the official Azure management REST API.
36+
37+
### List role definitions
38+
39+
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:
40+
41+
```bash
42+
az role definition list --output table
43+
```
44+
45+
```bash title="Output"
46+
Name Type Description
47+
--------------------------------------- --------------------------------------- -----------------------------------------------------------
48+
Contributor Microsoft.Authorization/roleDefinitions Grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC...
49+
Owner Microsoft.Authorization/roleDefinitions Grants full access to manage all resources, including assigning roles in Azure RBAC...
50+
Reader Microsoft.Authorization/roleDefinitions View all resources, but does not allow you to make any changes.
51+
...
52+
```
53+
54+
### Create a custom role definition
55+
56+
Save the following JSON to `custom-role.json`:
57+
58+
```json title="custom-role.json"
59+
{
60+
"Name": "Custom Storage Reader",
61+
"Description": "Can read storage blobs.",
62+
"Actions": [
63+
"Microsoft.Storage/storageAccounts/blobServices/containers/read"
64+
],
65+
"NotActions": [],
66+
"DataActions": [
67+
"Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
68+
],
69+
"NotDataActions": [],
70+
"AssignableScopes": [
71+
"/subscriptions/00000000-0000-0000-0000-000000000000"
72+
]
73+
}
74+
```
75+
76+
Then create the role:
77+
78+
```bash
79+
az role definition create --role-definition @custom-role.json
80+
```
81+
82+
```bash title="Output"
83+
{
84+
"assignableScopes": ["/subscriptions/00000000-0000-0000-0000-000000000000"],
85+
"description": "Can read storage blobs.",
86+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
87+
"name": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
88+
"permissions": [
89+
{
90+
"actions": [
91+
"Microsoft.Storage/storageAccounts/blobServices/containers/read"
92+
],
93+
"notActions": [],
94+
"dataActions": [
95+
"Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
96+
],
97+
"notDataActions": []
98+
}
99+
],
100+
"roleName": "Custom Storage Reader",
101+
"roleType": "CustomRole",
102+
"type": "Microsoft.Authorization/roleDefinitions"
103+
...
104+
}
105+
```
106+
107+
### List a role definition by name
108+
109+
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):
110+
111+
```bash
112+
az role definition list --name "Custom Storage Reader"
113+
```
114+
115+
```bash title="Output"
116+
[
117+
{
118+
"assignableScopes": ["/subscriptions/00000000-0000-0000-0000-000000000000"],
119+
"description": "Can read storage blobs.",
120+
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
121+
"name": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
122+
"permissions": [
123+
{
124+
"actions": [
125+
"Microsoft.Storage/storageAccounts/blobServices/containers/read"
126+
],
127+
"notActions": [],
128+
"dataActions": [
129+
"Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
130+
],
131+
"notDataActions": []
132+
}
133+
],
134+
"roleName": "Custom Storage Reader",
135+
"roleType": "CustomRole",
136+
"type": "Microsoft.Authorization/roleDefinitions"
137+
}
138+
]
139+
```
140+
141+
### Update a custom role definition
142+
143+
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:
144+
145+
```bash
146+
az role definition update --role-definition @custom-role.json
147+
```
148+
149+
### Delete a custom role definition
150+
151+
Delete the custom role definition by name:
152+
153+
```bash
154+
az role definition delete --name "Custom Storage Reader"
155+
az role definition list --name "Custom Storage Reader"
156+
```
157+
158+
## Features
159+
160+
- **Custom role creation:** Create custom role definitions with `Actions`, `NotActions`, `DataActions`, and `NotDataActions`.
161+
- **Built-in roles pre-populated:** Standard Azure built-in roles are available via `az role definition list`.
162+
- **Role listing and filtering:** List role definitions by name, scope, or custom flag.
163+
- **Role update:** Update existing custom role definitions including permissions and assignable scopes.
164+
- **Role deletion:** Delete custom role definitions by name or ID.
165+
- **Assignable scopes support:** Roles specify assignable scopes at subscription or resource group level.
166+
167+
## Limitations
168+
169+
- **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.
170+
- **Management group scopes:** Management group–level assignable scopes are not supported.
171+
172+
## Samples
173+
174+
Explore end-to-end examples in the [LocalStack for Azure Samples](https://github.com/localstack/localstack-azure-samples) repository.
175+
176+
## API Coverage
177+
178+
<AzureFeatureCoverage service="Microsoft.Authorization" client:load />

0 commit comments

Comments
 (0)