Skip to content

Commit 9895daf

Browse files
ttorblettorble
authored
Merge pull request #231257 from rolyon/rolyon-rbac-custom-roles-rest-api
[Azure RBAC] List custom role examples using REST API
2 parents 4a077f9 + e1230e3 commit 9895daf

File tree

2 files changed

+398
-108
lines changed

2 files changed

+398
-108
lines changed

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

Lines changed: 215 additions & 20 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,31 +34,71 @@ 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 role definitions
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 role definitions in a tenant, use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) REST API.
4040

41-
1. Start with the following request:
41+
- The following example lists all custom role definitions in a tenant:
4242

43+
**Request**
44+
4345
```http
44-
GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01&$filter={filter}
46+
GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01
47+
```
48+
49+
**Response**
50+
51+
```json
52+
{
53+
"value": [
54+
{
55+
"properties": {
56+
"roleName": "Billing Reader Plus",
57+
"type": "CustomRole",
58+
"description": "Read billing data and download invoices",
59+
"assignableScopes": [
60+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
61+
],
62+
"permissions": [
63+
{
64+
"actions": [
65+
"Microsoft.Authorization/*/read",
66+
"Microsoft.Billing/*/read",
67+
"Microsoft.Commerce/*/read",
68+
"Microsoft.Consumption/*/read",
69+
"Microsoft.Management/managementGroups/read",
70+
"Microsoft.CostManagement/*/read",
71+
"Microsoft.Billing/invoices/download/action",
72+
"Microsoft.CostManagement/exports/*"
73+
],
74+
"notActions": [
75+
"Microsoft.CostManagement/exports/delete"
76+
],
77+
"dataActions": [],
78+
"notDataActions": []
79+
}
80+
],
81+
"createdOn": "2021-05-22T21:57:23.5764138Z",
82+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
83+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
84+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
85+
},
86+
"id": "/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
87+
"type": "Microsoft.Authorization/roleDefinitions",
88+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
89+
}
90+
]
91+
}
4592
```
4693
47-
1. Replace *{filter}* with the role type.
48-
49-
> [!div class="mx-tableFixed"]
50-
> | Filter | Description |
51-
> | --- | --- |
52-
> | `$filter=type+eq+'CustomRole'` | Filter based on the CustomRole type |
53-
54-
## List custom roles at a scope
94+
## List all custom role definitions at a scope
5595
56-
To list custom roles at a scope, use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) REST API.
96+
To list custom role definitions at a scope, use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) REST API.
5797
5898
1. Start with the following request:
5999
60100
```http
61-
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01&$filter={filter}
101+
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
62102
```
63103
64104
1. Within the URI, replace *{scope}* with the scope for which you want to list the roles.
@@ -78,14 +118,67 @@ To list custom roles at a scope, use the [Role Definitions - List](/rest/api/aut
78118
> | --- | --- |
79119
> | `$filter=type+eq+'CustomRole'` | Filter based on the CustomRole type |
80120
121+
The following example lists all custom role definitions in a subscription:
122+
123+
**Request**
124+
125+
```http
126+
GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01
127+
```
128+
129+
**Response**
130+
131+
```json
132+
{
133+
"value": [
134+
{
135+
"properties": {
136+
"roleName": "Billing Reader Plus",
137+
"type": "CustomRole",
138+
"description": "Read billing data and download invoices",
139+
"assignableScopes": [
140+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
141+
],
142+
"permissions": [
143+
{
144+
"actions": [
145+
"Microsoft.Authorization/*/read",
146+
"Microsoft.Billing/*/read",
147+
"Microsoft.Commerce/*/read",
148+
"Microsoft.Consumption/*/read",
149+
"Microsoft.Management/managementGroups/read",
150+
"Microsoft.CostManagement/*/read",
151+
"Microsoft.Billing/invoices/download/action",
152+
"Microsoft.CostManagement/exports/*"
153+
],
154+
"notActions": [
155+
"Microsoft.CostManagement/exports/delete"
156+
],
157+
"dataActions": [],
158+
"notDataActions": []
159+
}
160+
],
161+
"createdOn": "2021-05-22T21:57:23.5764138Z",
162+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
163+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
164+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
165+
},
166+
"id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
167+
"type": "Microsoft.Authorization/roleDefinitions",
168+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
169+
}
170+
]
171+
}
172+
```
173+
81174
## List a custom role definition by name
82175
83-
To get information about a custom role by its display name, use the [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API.
176+
To get information about a custom role definition by its display name, use the [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API.
84177
85178
1. Start with the following request:
86179
87180
```http
88-
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01&$filter={filter}
181+
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01
89182
```
90183
91184
1. Within the URI, replace *{scope}* with the scope for which you want to list the roles.
@@ -105,9 +198,62 @@ To get information about a custom role by its display name, use the [Role Defini
105198
> | --- | --- |
106199
> | `$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'` |
107200
201+
The following example lists a custom role definition named Billing Reader Plus in a subscription:
202+
203+
**Request**
204+
205+
```http
206+
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
207+
```
208+
209+
**Response**
210+
211+
```json
212+
{
213+
"value": [
214+
{
215+
"properties": {
216+
"roleName": "Billing Reader Plus",
217+
"type": "CustomRole",
218+
"description": "Read billing data and download invoices",
219+
"assignableScopes": [
220+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
221+
],
222+
"permissions": [
223+
{
224+
"actions": [
225+
"Microsoft.Authorization/*/read",
226+
"Microsoft.Billing/*/read",
227+
"Microsoft.Commerce/*/read",
228+
"Microsoft.Consumption/*/read",
229+
"Microsoft.Management/managementGroups/read",
230+
"Microsoft.CostManagement/*/read",
231+
"Microsoft.Billing/invoices/download/action",
232+
"Microsoft.CostManagement/exports/*"
233+
],
234+
"notActions": [
235+
"Microsoft.CostManagement/exports/delete"
236+
],
237+
"dataActions": [],
238+
"notDataActions": []
239+
}
240+
],
241+
"createdOn": "2021-05-22T21:57:23.5764138Z",
242+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
243+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
244+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
245+
},
246+
"id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
247+
"type": "Microsoft.Authorization/roleDefinitions",
248+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
249+
}
250+
]
251+
}
252+
```
253+
108254
## List a custom role definition by ID
109255
110-
To get information about a custom role by its unique identifier, use the [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API.
256+
To get information about a custom role definition by its unique identifier, use the [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API.
111257
112258
1. Use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) REST API to get the GUID identifier for the role.
113259
@@ -129,6 +275,55 @@ To get information about a custom role by its unique identifier, use the [Role D
129275
130276
1. Replace *{roleDefinitionId}* with the GUID identifier of the role definition.
131277
278+
The following example lists a custom role definition with the identifier 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c in a subscription:
279+
280+
**Request**
281+
282+
```http
283+
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
284+
```
285+
286+
**Response**
287+
288+
```json
289+
{
290+
"properties": {
291+
"roleName": "Billing Reader Plus",
292+
"type": "CustomRole",
293+
"description": "Read billing data and download invoices",
294+
"assignableScopes": [
295+
"/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
296+
],
297+
"permissions": [
298+
{
299+
"actions": [
300+
"Microsoft.Authorization/*/read",
301+
"Microsoft.Billing/*/read",
302+
"Microsoft.Commerce/*/read",
303+
"Microsoft.Consumption/*/read",
304+
"Microsoft.Management/managementGroups/read",
305+
"Microsoft.CostManagement/*/read",
306+
"Microsoft.Billing/invoices/download/action",
307+
"Microsoft.CostManagement/exports/*"
308+
],
309+
"notActions": [
310+
"Microsoft.CostManagement/exports/delete"
311+
],
312+
"dataActions": [],
313+
"notDataActions": []
314+
}
315+
],
316+
"createdOn": "2021-05-22T21:57:23.5764138Z",
317+
"updatedOn": "2021-05-22T21:57:23.5764138Z",
318+
"createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
319+
"updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
320+
},
321+
"id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
322+
"type": "Microsoft.Authorization/roleDefinitions",
323+
"name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
324+
}
325+
```
326+
132327
## Create a custom role
133328
134329
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.
@@ -232,7 +427,7 @@ To create a custom role, use the [Role Definitions - Create Or Update](/rest/api
232427
233428
To update 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.
234429
235-
1. Use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) or [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API to get information about the custom role. For more information, see the earlier [List custom roles](#list-custom-roles) section.
430+
1. Use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) or [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API to get information about the custom role. For more information, see the earlier [List all custom role definitions](#list-all-custom-role-definitions) section.
236431
237432
1. Start with the following request:
238433
@@ -324,7 +519,7 @@ To delete a custom role, use the [Role Definitions - Delete](/rest/api/authoriza
324519
325520
1. Remove any role assignments that use the custom role. For more information, see [Find role assignments to delete a custom role](custom-roles.md#find-role-assignments-to-delete-a-custom-role).
326521
327-
1. Use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) or [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API to get the GUID identifier of the custom role. For more information, see the earlier [List custom roles](#list-custom-roles) section.
522+
1. Use the [Role Definitions - List](/rest/api/authorization/role-definitions/list) or [Role Definitions - Get](/rest/api/authorization/role-definitions/get) REST API to get the GUID identifier of the custom role. For more information, see the earlier [List all custom role definitions](#list-all-custom-role-definitions) section.
328523
329524
1. Start with the following request:
330525

0 commit comments

Comments
 (0)