Skip to content

Commit 6cd4b4b

Browse files
rolyonrolyon
committed
List custom role examples using REST API
1 parent 7bd15be commit 6cd4b4b

File tree

2 files changed

+313
-95
lines changed

2 files changed

+313
-95
lines changed

‎articles/role-based-access-control/custom-roles-rest.md

Lines changed: 215 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ ms.service: role-based-access-control
1212
ms.workload: multiple
1313
ms.tgt_pltfrm: rest-api
1414
ms.topic: how-to
15-
ms.date: 10/19/2022
15+
ms.date: 03/20/2023
1616
ms.author: rolyon
1717
ms.reviewer: bagovind
1818

@@ -34,14 +34,14 @@ You must use the following version:
3434

3535
For more information, see [API versions of Azure RBAC REST APIs](/rest/api/authorization/versions).
3636

37-
## List custom roles
37+
## List all custom roles in a tenant
3838

39-
To list all custom roles in a directory, use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) REST API.
39+
To list all custom roles in a tenant, use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) REST API.
4040

4141
1. Start with the following request:
4242

4343
```http
44-
GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01&$filter={filter}
44+
GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
4545
```
4646
4747
1. Replace *{filter}* with the role type.
@@ -51,14 +51,67 @@ To list all custom roles in a directory, use the [Role Definitions - List](/rest
5151
> | --- | --- |
5252
> | `$filter=type+eq+'CustomRole'` | Filter based on the CustomRole type |
5353
54-
## List custom roles at a scope
54+
The following example lists all custom roles in a tenant:
55+
56+
**Request**
57+
58+
```http
59+
GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01
60+
```
61+
62+
**Response**
63+
64+
```json
65+
{
66+
"value": [
67+
{
68+
"properties": {
69+
"roleName": "Billing Reader Plus",
70+
"type": "CustomRole",
71+
"description": "Read billing data and download invoices",
72+
"assignableScopes": [
73+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
74+
],
75+
"permissions": [
76+
{
77+
"actions": [
78+
"Microsoft.Authorization/*/read",
79+
"Microsoft.Billing/*/read",
80+
"Microsoft.Commerce/*/read",
81+
"Microsoft.Consumption/*/read",
82+
"Microsoft.Management/managementGroups/read",
83+
"Microsoft.CostManagement/*/read",
84+
"Microsoft.Billing/invoices/download/action",
85+
"Microsoft.CostManagement/exports/*"
86+
],
87+
"notActions": [
88+
"Microsoft.CostManagement/exports/delete"
89+
],
90+
"dataActions": [],
91+
"notDataActions": []
92+
}
93+
],
94+
"createdOn": "2021-05-22T21:57:23.5764138Z",
95+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
96+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
97+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
98+
},
99+
"id": "/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
100+
"type": "Microsoft.Authorization/roleDefinitions",
101+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
102+
}
103+
]
104+
}
105+
```
106+
107+
## List all custom roles at a scope
55108
56109
To list custom roles at a scope, use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) REST API.
57110
58111
1. Start with the following request:
59112
60113
```http
61-
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01&$filter={filter}
114+
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
62115
```
63116
64117
1. Within the URI, replace *{scope}* with the scope for which you want to list the roles.
@@ -78,14 +131,67 @@ To list custom roles at a scope, use the [Role Definitions - List](/rest/api/aut
78131
> | --- | --- |
79132
> | `$filter=type+eq+'CustomRole'` | Filter based on the CustomRole type |
80133
134+
The following example lists all custom roles in a subscription:
135+
136+
**Request**
137+
138+
```http
139+
GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01
140+
```
141+
142+
**Response**
143+
144+
```json
145+
{
146+
"value": [
147+
{
148+
"properties": {
149+
"roleName": "Billing Reader Plus",
150+
"type": "CustomRole",
151+
"description": "Read billing data and download invoices",
152+
"assignableScopes": [
153+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
154+
],
155+
"permissions": [
156+
{
157+
"actions": [
158+
"Microsoft.Authorization/*/read",
159+
"Microsoft.Billing/*/read",
160+
"Microsoft.Commerce/*/read",
161+
"Microsoft.Consumption/*/read",
162+
"Microsoft.Management/managementGroups/read",
163+
"Microsoft.CostManagement/*/read",
164+
"Microsoft.Billing/invoices/download/action",
165+
"Microsoft.CostManagement/exports/*"
166+
],
167+
"notActions": [
168+
"Microsoft.CostManagement/exports/delete"
169+
],
170+
"dataActions": [],
171+
"notDataActions": []
172+
}
173+
],
174+
"createdOn": "2021-05-22T21:57:23.5764138Z",
175+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
176+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
177+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
178+
},
179+
"id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
180+
"type": "Microsoft.Authorization/roleDefinitions",
181+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
182+
}
183+
]
184+
}
185+
```
186+
81187
## List a custom role definition by name
82188
83189
To get information about a custom role by its display name, use the [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API.
84190
85191
1. Start with the following request:
86192
87193
```http
88-
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01&$filter={filter}
194+
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
89195
```
90196
91197
1. Within the URI, replace *{scope}* with the scope for which you want to list the roles.
@@ -105,6 +211,59 @@ To get information about a custom role by its display name, use the [Role Defini
105211
> | --- | --- |
106212
> | `$filter=roleName+eq+'{roleDisplayName}'` | Use the URL encoded form of the exact display name of the role. For instance, `$filter=roleName+eq+'Virtual%20Machine%20Contributor'` |
107213
214+
The following example lists a custom role named Billing Reader Plus in a subscription:
215+
216+
**Request**
217+
218+
```http
219+
GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=roleName+eq+'Billing Reader Plus'&api-version=2022-04-01
220+
```
221+
222+
**Response**
223+
224+
```json
225+
{
226+
"value": [
227+
{
228+
"properties": {
229+
"roleName": "Billing Reader Plus",
230+
"type": "CustomRole",
231+
"description": "Read billing data and download invoices",
232+
"assignableScopes": [
233+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
234+
],
235+
"permissions": [
236+
{
237+
"actions": [
238+
"Microsoft.Authorization/*/read",
239+
"Microsoft.Billing/*/read",
240+
"Microsoft.Commerce/*/read",
241+
"Microsoft.Consumption/*/read",
242+
"Microsoft.Management/managementGroups/read",
243+
"Microsoft.CostManagement/*/read",
244+
"Microsoft.Billing/invoices/download/action",
245+
"Microsoft.CostManagement/exports/*"
246+
],
247+
"notActions": [
248+
"Microsoft.CostManagement/exports/delete"
249+
],
250+
"dataActions": [],
251+
"notDataActions": []
252+
}
253+
],
254+
"createdOn": "2021-05-22T21:57:23.5764138Z",
255+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
256+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
257+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
258+
},
259+
"id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
260+
"type": "Microsoft.Authorization/roleDefinitions",
261+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
262+
}
263+
]
264+
}
265+
```
266+
108267
## List a custom role definition by ID
109268
110269
To get information about a custom role by its unique identifier, use the [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API.
@@ -129,6 +288,55 @@ To get information about a custom role by its unique identifier, use the [Role D
129288
130289
1. Replace *{roleDefinitionId}* with the GUID identifier of the role definition.
131290
291+
The following example lists a custom role with the identifier 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c in a subscription:
292+
293+
**Request**
294+
295+
```http
296+
GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c?api-version=2022-04-01
297+
```
298+
299+
**Response**
300+
301+
```json
302+
{
303+
"properties": {
304+
"roleName": "Billing Reader Plus",
305+
"type": "CustomRole",
306+
"description": "Read billing data and download invoices",
307+
"assignableScopes": [
308+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
309+
],
310+
"permissions": [
311+
{
312+
"actions": [
313+
"Microsoft.Authorization/*/read",
314+
"Microsoft.Billing/*/read",
315+
"Microsoft.Commerce/*/read",
316+
"Microsoft.Consumption/*/read",
317+
"Microsoft.Management/managementGroups/read",
318+
"Microsoft.CostManagement/*/read",
319+
"Microsoft.Billing/invoices/download/action",
320+
"Microsoft.CostManagement/exports/*"
321+
],
322+
"notActions": [
323+
"Microsoft.CostManagement/exports/delete"
324+
],
325+
"dataActions": [],
326+
"notDataActions": []
327+
}
328+
],
329+
"createdOn": "2021-05-22T21:57:23.5764138Z",
330+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
331+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
332+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
333+
},
334+
"id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
335+
"type": "Microsoft.Authorization/roleDefinitions",
336+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
337+
}
338+
```
339+
132340
## Create a custom role
133341
134342
To create a custom role, use the [Role Definitions - Create Or Update](/rest/api/authorization/role-definitions/create-or-update) REST API. To call this API, you must be signed in with a user that is assigned a role that has the `Microsoft.Authorization/roleDefinitions/write` permission on all the `assignableScopes`. Of the built-in roles, only [Owner](built-in-roles.md#owner) and [User Access Administrator](built-in-roles.md#user-access-administrator) include this permission.

0 commit comments

Comments
 (0)