Skip to content

Commit def1a35

Browse files
rolyonrolyon
committed
Added custom role formats
1 parent 5a5edee commit def1a35

File tree

1 file changed

+189
-8
lines changed

1 file changed

+189
-8
lines changed

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

Lines changed: 189 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ ms.devlang: na
1212
ms.topic: conceptual
1313
ms.tgt_pltfrm: na
1414
ms.workload: identity
15-
ms.date: 04/30/2020
15+
ms.date: 05/07/2020
1616
ms.author: rolyon
1717
ms.reviewer: bagovind
1818
ms.custom: H1Hack27Feb2017
@@ -31,7 +31,11 @@ Custom roles can be shared between subscriptions that trust the same Azure AD di
3131

3232
## Custom role example
3333

34-
The following shows what a custom role looks like as displayed in JSON format. This custom role can be used for monitoring and restarting virtual machines.
34+
When you create a custom role, it appears in the Azure portal with an orange resource icon.
35+
36+
![Custom role icon](./media/custom-roles/roles-custom-role-icon.png)
37+
38+
The following shows what a custom role looks like as displayed using Azure PowerShell in JSON format. This custom role can be used for monitoring and restarting virtual machines.
3539

3640
```json
3741
{
@@ -63,9 +67,45 @@ The following shows what a custom role looks like as displayed in JSON format. T
6367
}
6468
```
6569

66-
When you create a custom role, it appears in the Azure portal with an orange resource icon.
70+
The following shows the same custom role as displayed using Azure CLI.
6771

68-
![Custom role icon](./media/custom-roles/roles-custom-role-icon.png)
72+
```json
73+
[
74+
{
75+
"assignableScopes": [
76+
"/subscriptions/{subscriptionId1}",
77+
"/subscriptions/{subscriptionId2}",
78+
"/providers/Microsoft.Management/managementGroups/{groupId1}"
79+
],
80+
"description": "Can monitor and restart virtual machines.",
81+
"id": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/88888888-8888-8888-8888-888888888888",
82+
"name": "88888888-8888-8888-8888-888888888888",
83+
"permissions": [
84+
{
85+
"actions": [
86+
"Microsoft.Storage/*/read",
87+
"Microsoft.Network/*/read",
88+
"Microsoft.Compute/*/read",
89+
"Microsoft.Compute/virtualMachines/start/action",
90+
"Microsoft.Compute/virtualMachines/restart/action",
91+
"Microsoft.Authorization/*/read",
92+
"Microsoft.ResourceHealth/availabilityStatuses/read",
93+
"Microsoft.Resources/subscriptions/resourceGroups/read",
94+
"Microsoft.Insights/alertRules/*",
95+
"Microsoft.Insights/diagnosticSettings/*",
96+
"Microsoft.Support/*"
97+
],
98+
"dataActions": [],
99+
"notActions": [],
100+
"notDataActions": []
101+
}
102+
],
103+
"roleName": "Virtual Machine Operator",
104+
"roleType": "CustomRole",
105+
"type": "Microsoft.Authorization/roleDefinitions"
106+
}
107+
]
108+
```
69109

70110
## Steps to create a custom role
71111

@@ -75,17 +115,17 @@ When you create a custom role, it appears in the Azure portal with an orange res
75115

76116
1. Determine the permissions you need
77117

78-
When you create a custom role, you need to know the resource provider operations that are available to define your permissions. To view the list of operations, see the [Azure Resource Manager resource provider operations](resource-provider-operations.md). You will add the operations to the `Actions` or `NotActions` properties of the [role definition](role-definitions.md). If you have data operations, you will add those to the `DataActions` or `NotDataActions` properties.
118+
When you create a custom role, you need to know the operations that are available to define your permissions. To view the list of operations, see the [Azure Resource Manager resource provider operations](resource-provider-operations.md). You will add the operations to the `Actions` or `NotActions` properties of the [role definition](role-definitions.md). If you have data operations, you will add those to the `DataActions` or `NotDataActions` properties.
79119

80120
1. Create the custom role
81121

82-
Typically, you start with an existing built-in role and then modify it for your needs. Then you use the [New-AzRoleDefinition](/powershell/module/az.resources/new-azroledefinition) or [az role definition create](/cli/azure/role/definition#az-role-definition-create) commands to create the custom role. To create a custom role, you must have the `Microsoft.Authorization/roleDefinitions/write` permission on all `AssignableScopes`, such as [Owner](built-in-roles.md#owner) or [User Access Administrator](built-in-roles.md#user-access-administrator).
122+
Typically, you start with an existing built-in role and then modify it for your needs. The easiest way to create a custom role is to use the Azure portal, but can you can also create custom roles using commands. To create a custom role, you must be signed in with a user that has the `Microsoft.Authorization/roleDefinitions/write` permission on all `AssignableScopes`, such as [Owner](built-in-roles.md#owner) or [User Access Administrator](built-in-roles.md#user-access-administrator).
83123

84124
1. Test the custom role
85125

86126
Once you have your custom role, you have to test it to verify that it works as you expect. If you need to make adjustments later, you can update the custom role.
87127

88-
For a step-by-step tutorial on how to create a custom role, see [Tutorial: Create an Azure custom role using Azure PowerShell](tutorial-custom-role-powershell.md) or [Tutorial: Create an Azure custom role using Azure CLI](tutorial-custom-role-cli.md).
128+
For steps on how to create a custom role using the Azure portal, see [Create or update Azure custom roles using the Azure portal](custom-roles-portal.md).
89129

90130
## Custom role properties
91131

@@ -126,7 +166,148 @@ The following list describes the limits for custom roles.
126166

127167
For more information about custom roles and management groups, see [Organize your resources with Azure management groups](../governance/management-groups/overview.md#custom-rbac-role-definition-and-assignment).
128168

169+
## Custom role formats
170+
171+
To create a custom role using the command line, you typically use JSON to specify the properties you want for the custom role. Depending on the tools you use, the JSON format will look slightly different. The following shows the JSON format depending on the tool.
172+
173+
### Azure PowerShell
174+
175+
To create a custom role using Azure PowerShell, you must provide following input.
176+
177+
```json
178+
{
179+
"Name": "",
180+
"Description": "",
181+
"Actions": [],
182+
"NotActions": [],
183+
"DataActions": [],
184+
"NotDataActions": [],
185+
"AssignableScopes": []
186+
}
187+
```
188+
189+
To update a custom role using Azure PowerShell, you must provide the following input. Note that the `Id` property has been added.
190+
191+
```json
192+
{
193+
"Name": "",
194+
"Id": "",
195+
"Description": "",
196+
"Actions": [],
197+
"NotActions": [],
198+
"DataActions": [],
199+
"NotDataActions": [],
200+
"AssignableScopes": []
201+
}
202+
```
203+
204+
The following shows an example of the output when listing a custom role using Azure PowerShell and the [ConvertTo-Json](/powershell/module/microsoft.powershell.utility/convertto-json) command.
205+
206+
```json
207+
{
208+
"Name": "",
209+
"Id": "",
210+
"IsCustom": true,
211+
"Description": "",
212+
"Actions": [],
213+
"NotActions": [],
214+
"DataActions": [],
215+
"NotDataActions": [],
216+
"AssignableScopes": []
217+
}
218+
```
219+
220+
### Azure CLI
221+
222+
To create or update a custom role using Azure CLI, you must provide following input. This format is the same format when you create a custom role using Azure PowerShell.
223+
224+
```json
225+
{
226+
"Name": "",
227+
"Description": "",
228+
"Actions": [],
229+
"NotActions": [],
230+
"DataActions": [],
231+
"NotDataActions": [],
232+
"AssignableScopes": []
233+
}
234+
```
235+
236+
The following shows an example of the output when listing a custom role using Azure CLI.
237+
238+
```json
239+
[
240+
{
241+
"assignableScopes": [],
242+
"description": "",
243+
"id": "",
244+
"name": "",
245+
"permissions": [
246+
{
247+
"actions": [],
248+
"dataActions": [],
249+
"notActions": [],
250+
"notDataActions": []
251+
}
252+
],
253+
"roleName": "",
254+
"roleType": "CustomRole",
255+
"type": "Microsoft.Authorization/roleDefinitions"
256+
}
257+
]
258+
```
259+
260+
### REST API
261+
262+
To create or update a custom role using the REST API, you must provide following input. This format is the same format that gets generated when you create a custom role using the Azure portal.
263+
264+
```json
265+
{
266+
"properties": {
267+
"roleName": "",
268+
"description": "",
269+
"assignableScopes": [],
270+
"permissions": [
271+
{
272+
"actions": [],
273+
"notActions": [],
274+
"dataActions": [],
275+
"notDataActions": []
276+
}
277+
]
278+
}
279+
}
280+
```
281+
282+
The following shows an example of the output when listing a custom role using the REST API.
283+
284+
```json
285+
{
286+
"properties": {
287+
"roleName": "",
288+
"type": "CustomRole",
289+
"description": "",
290+
"assignableScopes": [],
291+
"permissions": [
292+
{
293+
"actions": [],
294+
"notActions": []
295+
}
296+
],
297+
"createdOn": "",
298+
"updatedOn": "",
299+
"createdBy": "",
300+
"updatedBy": ""
301+
},
302+
"id": "",
303+
"type": "Microsoft.Authorization/roleDefinitions",
304+
"name": ""
305+
}
306+
```
307+
129308
## Next steps
130-
- [Create or update Azure custom roles using the Azure portal](custom-roles-portal.md)
309+
310+
- [Tutorial: Create an Azure custom role using Azure PowerShell](tutorial-custom-role-powershell.md)
311+
- [Tutorial: Create an Azure custom role using Azure CLI](tutorial-custom-role-cli.md)
131312
- [Understand Azure role definitions](role-definitions.md)
132313
- [Troubleshoot Azure RBAC](troubleshooting.md)

0 commit comments

Comments
 (0)