Skip to content

Commit 27513d2

Browse files
ShannonLeavittShannonLeavitt
authored
Merge pull request #114426 from rolyon/rolyon-rbac-custom-roles-format
[Azure RBAC] custom roles format
2 parents 3d3c48b + 64958be commit 27513d2

File tree

2 files changed

+311
-40
lines changed

2 files changed

+311
-40
lines changed

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

Lines changed: 209 additions & 26 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/08/2020
1616
ms.author: rolyon
1717
ms.reviewer: bagovind
1818
ms.custom: H1Hack27Feb2017
@@ -31,7 +31,7 @@ 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+
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.
3535

3636
```json
3737
{
@@ -63,45 +63,85 @@ The following shows what a custom role looks like as displayed in JSON format. T
6363
}
6464
```
6565

66+
The following shows the same custom role as displayed using Azure CLI.
67+
68+
```json
69+
[
70+
{
71+
"assignableScopes": [
72+
"/subscriptions/{subscriptionId1}",
73+
"/subscriptions/{subscriptionId2}",
74+
"/providers/Microsoft.Management/managementGroups/{groupId1}"
75+
],
76+
"description": "Can monitor and restart virtual machines.",
77+
"id": "/subscriptions/{subscriptionId1}/providers/Microsoft.Authorization/roleDefinitions/88888888-8888-8888-8888-888888888888",
78+
"name": "88888888-8888-8888-8888-888888888888",
79+
"permissions": [
80+
{
81+
"actions": [
82+
"Microsoft.Storage/*/read",
83+
"Microsoft.Network/*/read",
84+
"Microsoft.Compute/*/read",
85+
"Microsoft.Compute/virtualMachines/start/action",
86+
"Microsoft.Compute/virtualMachines/restart/action",
87+
"Microsoft.Authorization/*/read",
88+
"Microsoft.ResourceHealth/availabilityStatuses/read",
89+
"Microsoft.Resources/subscriptions/resourceGroups/read",
90+
"Microsoft.Insights/alertRules/*",
91+
"Microsoft.Insights/diagnosticSettings/*",
92+
"Microsoft.Support/*"
93+
],
94+
"dataActions": [],
95+
"notActions": [],
96+
"notDataActions": []
97+
}
98+
],
99+
"roleName": "Virtual Machine Operator",
100+
"roleType": "CustomRole",
101+
"type": "Microsoft.Authorization/roleDefinitions"
102+
}
103+
]
104+
```
105+
66106
When you create a custom role, it appears in the Azure portal with an orange resource icon.
67107

68108
![Custom role icon](./media/custom-roles/roles-custom-role-icon.png)
69109

70-
## Steps to create a custom role
110+
## Custom role properties
71111

72-
1. Decide how you want to create the custom role
112+
The following table describes what the custom role properties mean.
73113

74-
You can create custom roles using [Azure portal](custom-roles-portal.md), [Azure PowerShell](custom-roles-powershell.md), [Azure CLI](custom-roles-cli.md), or the [REST API](custom-roles-rest.md).
114+
| Property | Required | Type | Description |
115+
| --- | --- | --- | --- |
116+
| `Name`</br>`roleName` | Yes | String | The display name of the custom role. While a role definition is a management group or subscription-level resource, a role definition can be used in multiple subscriptions that share the same Azure AD directory. This display name must be unique at the scope of the Azure AD directory. Can include letters, numbers, spaces, and special characters. Maximum number of characters is 128. |
117+
| `Id`</br>`name` | Yes | String | The unique ID of the custom role. For Azure PowerShell and Azure CLI, this ID is automatically generated when you create a new role. |
118+
| `IsCustom`</br>`roleType` | Yes | String | Indicates whether this is a custom role. Set to `true` or `CustomRole` for custom roles. Set to `false` or `BuiltInRole` for built-in roles. |
119+
| `Description`</br>`description` | Yes | String | The description of the custom role. Can include letters, numbers, spaces, and special characters. Maximum number of characters is 1024. |
120+
| `Actions`</br>`actions` | Yes | String[] | An array of strings that specifies the management operations that the role allows to be performed. For more information, see [Actions](role-definitions.md#actions). |
121+
| `NotActions`</br>`notActions` | No | String[] | An array of strings that specifies the management operations that are excluded from the allowed `Actions`. For more information, see [NotActions](role-definitions.md#notactions). |
122+
| `DataActions`</br>`dataActions` | No | String[] | An array of strings that specifies the data operations that the role allows to be performed to your data within that object. If you create a custom role with `DataActions`, that role cannot be assigned at the management group scope. For more information, see [DataActions](role-definitions.md#dataactions). |
123+
| `NotDataActions`</br>`notDataActions` | No | String[] | An array of strings that specifies the data operations that are excluded from the allowed `DataActions`. For more information, see [NotDataActions](role-definitions.md#notdataactions). |
124+
| `AssignableScopes`</br>`assignableScopes` | Yes | String[] | An array of strings that specifies the scopes that the custom role is available for assignment. You can only define one management group in `AssignableScopes` of a custom role. Adding a management group to `AssignableScopes` is currently in preview. For more information, see [AssignableScopes](role-definitions.md#assignablescopes). |
75125

76-
1. Determine the permissions you need
126+
## Steps to create a custom role
77127

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.
128+
To create a custom role, here are basics steps you should follow.
79129

80-
1. Create the custom role
130+
1. Decide how you want to create the custom role.
81131

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).
132+
You can create custom roles using Azure portal, Azure PowerShell, Azure CLI, or the REST API.
83133

84-
1. Test the custom role
134+
1. Determine the permissions you need.
85135

86-
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.
136+
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.
87137

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).
138+
1. Create the custom role.
89139

90-
## Custom role properties
140+
Typically, you start with an existing built-in role and then modify it for your needs. The easiest way is to use the Azure portal. 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).
91141

92-
A custom role has the following properties.
142+
1. Test the custom role.
93143

94-
| Property | Required | Type | Description |
95-
| --- | --- | --- | --- |
96-
| `Name` | Yes | String | The display name of the custom role. While a role definition is a management group or subscription-level resource, a role definition can be used in multiple subscriptions that share the same Azure AD directory. This display name must be unique at the scope of the Azure AD directory. Can include letters, numbers, spaces, and special characters. Maximum number of characters is 128. |
97-
| `Id` | Yes | String | The unique ID of the custom role. For Azure PowerShell and Azure CLI, this ID is automatically generated when you create a new role. |
98-
| `IsCustom` | Yes | String | Indicates whether this is a custom role. Set to `true` for custom roles. |
99-
| `Description` | Yes | String | The description of the custom role. Can include letters, numbers, spaces, and special characters. Maximum number of characters is 1024. |
100-
| `Actions` | Yes | String[] | An array of strings that specifies the management operations that the role allows to be performed. For more information, see [Actions](role-definitions.md#actions). |
101-
| `NotActions` | No | String[] | An array of strings that specifies the management operations that are excluded from the allowed `Actions`. For more information, see [NotActions](role-definitions.md#notactions). |
102-
| `DataActions` | No | String[] | An array of strings that specifies the data operations that the role allows to be performed to your data within that object. If you create a custom role with `DataActions`, that role cannot be assigned at the management group scope. For more information, see [DataActions](role-definitions.md#dataactions). |
103-
| `NotDataActions` | No | String[] | An array of strings that specifies the data operations that are excluded from the allowed `DataActions`. For more information, see [NotDataActions](role-definitions.md#notdataactions). |
104-
| `AssignableScopes` | Yes | String[] | An array of strings that specifies the scopes that the custom role is available for assignment. You can only define one management group in `AssignableScopes` of a custom role. Adding a management group to `AssignableScopes` is currently in preview. For more information, see [AssignableScopes](role-definitions.md#assignablescopes). |
144+
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.
105145

106146
## Who can create, delete, update, or view a custom role
107147

@@ -126,7 +166,150 @@ 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+
## Input and output 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 input and output formats will look slightly different. This section lists the input and output formats 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 you list 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 you list 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 you list 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+
"dataActions": [],
296+
"notDataActions": []
297+
}
298+
],
299+
"createdOn": "",
300+
"updatedOn": "",
301+
"createdBy": "",
302+
"updatedBy": ""
303+
},
304+
"id": "",
305+
"type": "Microsoft.Authorization/roleDefinitions",
306+
"name": ""
307+
}
308+
```
309+
129310
## Next steps
130-
- [Create or update Azure custom roles using the Azure portal](custom-roles-portal.md)
311+
312+
- [Tutorial: Create an Azure custom role using Azure PowerShell](tutorial-custom-role-powershell.md)
313+
- [Tutorial: Create an Azure custom role using Azure CLI](tutorial-custom-role-cli.md)
131314
- [Understand Azure role definitions](role-definitions.md)
132315
- [Troubleshoot Azure RBAC](troubleshooting.md)

0 commit comments

Comments
 (0)