Skip to content

Commit 2a0ab1d

Browse files
jborsecnikjborsecnik
authored
Merge pull request #211519 from johndowns/rbac-understand-role-assignments
Azure RBAC - Add role assignments conceptual article
2 parents 6156fec + c050c38 commit 2a0ab1d

File tree

5 files changed

+195
-11
lines changed

5 files changed

+195
-11
lines changed

‎articles/azure-resource-manager/bicep/scenarios-rbac.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ If you don't explicitly specify the scope, Bicep uses the file's `targetScope`.
2929
::: code language="bicep" source="~/azure-docs-bicep-samples/samples/scenarios-rbac/scope-default.bicep" highlight="4" :::
3030

3131
> [!TIP]
32-
> Ensure you use the smallest scope required for your requirements.
32+
> Use the smallest scope that you need to meet your requirements.
3333
>
3434
> For example, if you need to grant a managed identity access to a single storage account, it's good security practice to create the role assignment at the scope of the storage account, not at the resource group or subscription scope.
3535

‎articles/role-based-access-control/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@
3535
items:
3636
- name: Role definitions
3737
href: role-definitions.md
38+
- name: Role assignments
39+
href: role-assignments.md
3840
- name: Scope
3941
href: scope-overview.md
4042
- name: Best practices

‎articles/role-based-access-control/role-assignments.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: Understand Azure role assignments - Azure RBAC
3+
description: Learn about Azure role assignments in Azure role-based access control (Azure RBAC) for fine-grained access management of Azure resources.
4+
services: active-directory
5+
documentationcenter: ''
6+
author: johndowns
7+
ms.service: role-based-access-control
8+
ms.topic: conceptual
9+
ms.workload: identity
10+
ms.date: 10/03/2022
11+
ms.author: jodowns
12+
---
13+
# Understand Azure role assignments
14+
15+
Role assignments enable you to grant a principal (such as a user, a group, a managed identity, or a service principal) access to a specific Azure resource. This article describes the details of role assignments.
16+
17+
## Role assignment
18+
19+
Access to Azure resources is granted by creating a role assignment, and access is revoked by removing a role assignment.
20+
21+
A role assignment has several components, including:
22+
23+
- The *principal*, or *who* is assigned the role.
24+
- The *role* that they're assigned.
25+
- The *scope* at which the role is assigned.
26+
- The *name* of the role assignment, and a *description* that helps you to explain why the role has been assigned.
27+
28+
For example, you can use Azure RBAC to assign roles like:
29+
30+
- User Sally has owner access to the storage account *contoso123* in the resource group *ContosoStorage*.
31+
- Everybody in the Cloud Administrators group in Azure Active Directory has reader access to all resources in the resource group *ContosoStorage*.
32+
- The managed identity associated with an application is allowed to restart virtual machines within Contoso's subscription.
33+
34+
The following shows an example of the properties in a role assignment when displayed using [Azure PowerShell](role-assignments-list-powershell.md):
35+
36+
```json
37+
{
38+
"RoleAssignmentName": "00000000-0000-0000-0000-000000000000",
39+
"RoleAssignmentId": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.Authorization/roleAssignments/00000000-0000-0000-0000-000000000000",
40+
"Scope": "/subscriptions/11111111-1111-1111-1111-111111111111",
41+
"DisplayName": "User Name",
42+
"SignInName": "[email protected]",
43+
"RoleDefinitionName": "Contributor",
44+
"RoleDefinitionId": "b24988ac-6180-42a0-ab88-20f7382dd24c",
45+
"ObjectId": "22222222-2222-2222-2222-222222222222",
46+
"ObjectType": "User",
47+
"CanDelegate": false,
48+
"Description": null,
49+
"ConditionVersion": null,
50+
"Condition": null
51+
}
52+
```
53+
54+
The following shows an example of the properties in a role assignment when displayed using the [Azure CLI](role-assignments-list-cli.md), or the [REST API](role-assignments-list-rest.md):
55+
56+
```json
57+
{
58+
"canDelegate": null,
59+
"condition": null,
60+
"conditionVersion": null,
61+
"description": null,
62+
"id": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.Authorization/roleAssignments/00000000-0000-0000-0000-000000000000",
63+
"name": "00000000-0000-0000-0000-000000000000",
64+
"principalId": "22222222-2222-2222-2222-222222222222",
65+
"principalName": "[email protected]",
66+
"principalType": "User",
67+
"roleDefinitionId": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
68+
"roleDefinitionName": "Contributor",
69+
"scope": "/subscriptions/11111111-1111-1111-1111-111111111111",
70+
"type": "Microsoft.Authorization/roleAssignments"
71+
}
72+
```
73+
74+
The following table describes what the role assignment properties mean.
75+
76+
| Property | Description |
77+
| --- | --- |
78+
| `RoleAssignmentName`<br />`name` | The name of the role assignment, which is a globally unique identifier (GUID). |
79+
| `RoleAssignmentId`<br />`id` | The unique ID of the role assignment, which includes the name. |
80+
| `Scope`<br />`scope` | The Azure resource identifier that the role assignment is scoped to. |
81+
| `RoleDefinitionId`<br />`roleDefinitionId` | The unique ID of the role. |
82+
| `RoleDefinitionName`<br />`roleDefinitionName` | The name of the role. |
83+
| `ObjectId`<br />`principalId` | The Azure Active Directory (Azure AD) object identifier for the principal who has the role assigned. |
84+
| `ObjectType`<br />`principalType` | The type of Azure AD object that the principal represents. Valid values include `User`, `Group`, and `ServicePrincipal`. |
85+
| `DisplayName` | For role assignments for users, the display name of the user. |
86+
| `SignInName`<br />`principalName` | The unique principal name (UPN) of the user, or the name of the application associated with the service principal. |
87+
| `Description`<br />`description` | The description of the role assignment. |
88+
| `Condition`<br />`condition` | Condition statement built using one or more actions from role definition and attributes. |
89+
| `ConditionVersion`<br />`conditionVersion` | The condition version number. Defaults to 2.0 and is the only supported version. |
90+
| `CanDelegate`<br />`canDelegate` | Not implemented. |
91+
92+
## Scope
93+
94+
When you create a role assignment, you need to specify the scope at which it's applied. The scope represents the resource, or set of resources, that the principal is allowed to access. You can scope a role assignment to a single resource, a resource group, a subscription, or a management group.
95+
96+
> [!TIP]
97+
> Use the smallest scope that you need to meet your requirements.
98+
>
99+
> For example, if you need to grant a managed identity access to a single storage account, it's good security practice to create the role assignment at the scope of the storage account, not at the resource group or subscription scope.
100+
101+
For more information about scope, see [Understand scope](scope-overview.md).
102+
103+
## Role to assign
104+
105+
A role assignment is associated with a role definition. The role definition specifies the permissions that the principal should have within the role assignment's scope.
106+
107+
You can assign a built-in role definition or a custom role definition. When you create a role assignment, some tooling requires that you use the role definition ID while other tooling allows you to provide the name of the role.
108+
109+
For more information about role definitions, see [Understand role definitions](role-definitions.md).
110+
111+
## Principal
112+
113+
Principals include users, security groups, managed identities, workload identities, and service principals. Principals are created and managed in your Azure Active Directory (Azure AD) tenant. You can assign a role to any principal. Use the Azure AD *object ID* to identify the principal that you want to assign the role to.
114+
115+
When you create a role assignment by using Azure PowerShell, the Azure CLI, Bicep, or another infrastructure as code (IaC) technology, you specify the *principal type*. Principal types include *User*, *Group*, and *ServicePrincipal*. It's important to specify the correct principal type. Otherwise, you might get intermittent deployment errors, especially when you work with service principals and managed identities.
116+
117+
## Name
118+
119+
A role assignment's resource name must be a globally unique identifier (GUID).
120+
121+
Role assignment resource names must be unique within the Azure Active Directory tenant, even if the scope of the role assignment is narrower.
122+
123+
> [!TIP]
124+
> When you create a role assignment by using the Azure portal, Azure PowerShell, or the Azure CLI, the creation process gives the role assignment a unique name for you automatically.
125+
>
126+
> If you create a role assignment by using Bicep or another infrastructure as code (IaC) technology, you need to carefully plan how you name your role assignments. For more information, see [Create Azure RBAC resources by using Bicep](../azure-resource-manager/bicep/scenarios-rbac.md).
127+
128+
### Resource deletion behavior
129+
130+
When you delete a user, group, service principal, or managed identity from Azure AD, it's a good practice to delete any role assignments. They aren't deleted automatically. Any role assignments that refer to a deleted principal ID become invalid.
131+
132+
If you try to reuse a role assignment's name for another role assignment, the deployment will fail. This issue is more likely to occur when you use Bicep or an Azure Resource Manager template (ARM template) to deploy your role assignments, because you have to explicitly set the role assignment name when you use these tools. To work around this behavior, you should either remove the old role assignment before you recreate it, or ensure that you use a unique name when you deploy a new role assignment.
133+
134+
## Description
135+
136+
You can add a text description to a role assignment. While descriptions are optional, it's a good practice to add them to your role assignments. Provide a short justification for why the principal needs the assigned role. When somebody audits the role assignments, descriptions can help to understand why they've been created and whether they're still applicable.
137+
138+
## Conditions
139+
140+
Some roles support *role assignment conditions* based on attributes in the context of specific actions. A role assignment condition is an additional check that you can optionally add to your role assignment to provide more fine-grained access control.
141+
142+
For example, you can add a condition that requires an object to have a specific tag for the user to read the object.
143+
144+
You typically build conditions using a visual condition editor, but here's what an example condition looks like in code:
145+
146+
```
147+
((!(ActionMatches{'Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read'} AND NOT SubOperationMatches{'Blob.List'})) OR (@resource[Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags:Project<$key_case_sensitive$>] StringEqualsIgnoreCase 'Cascade'))
148+
```
149+
150+
The preceding condition allows users to read blobs with a blob index tag key of *Project* and a value of *Cascade*.
151+
152+
For more information about conditions, see [What is Azure attribute-based access control (Azure ABAC)?](conditions-overview.md)
153+
154+
## Next steps
155+
156+
* [Understand role definitions](role-definitions.md)

‎articles/role-based-access-control/role-definitions.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -361,6 +361,7 @@ For more information about `AssignableScopes` for custom roles, see [Azure custo
361361

362362
## Next steps
363363

364+
* [Understand role assignments](role-assignments.md)
364365
* [Azure built-in roles](built-in-roles.md)
365366
* [Azure custom roles](custom-roles.md)
366367
* [Azure resource provider operations](resource-provider-operations.md)

‎articles/role-based-access-control/troubleshooting.md

Lines changed: 35 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -122,29 +122,54 @@ Set the `principalType` property to `ServicePrincipal` when creating the role as
122122

123123
### Symptom - ARM template role assignment returns BadRequest status
124124

125-
When you try to deploy an ARM template that assigns a role to a service principal you get the error:
125+
When you try to deploy a Bicep file or ARM template that assigns a role to a service principal you get the error:
126126

127127
`Tenant ID, application ID, principal ID, and scope are not allowed to be updated. (code: RoleAssignmentUpdateNotPermitted)`
128128

129+
For example, if you create a role assignment for a managed identity, then you delete the managed identity and recreate it, the new managed identity has a different principal ID. If you try to deploy the role assignment again and use the same role assignment name, the deployment fails.
130+
129131
**Cause**
130132

131133
The role assignment `name` is not unique, and it is viewed as an update.
132134

135+
Role assignments are uniquely identified by their name, which is a globally unique identifier (GUID). You can't create two role assignments with the same name, even in different Azure subscriptions. You also can't change the properties of an existing role assignment.
136+
133137
**Solution**
134-
Provide an idempotent unique value for the role assignment `name`
135138

139+
Provide an idempotent unique value for the role assignment `name`. It's a good practice to create a GUID that uses the scope, principal ID, and role ID together. It's a good idea to use the `guid()` function to help you to create a deterministic GUID for your role assignment names, like in this example:
140+
141+
# [Bicep](#tab/bicep)
142+
143+
```bicep
144+
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2020-10-01-preview' = {
145+
name: guid(resourceGroup().id, principalId, roleDefinitionId)
146+
properties: {
147+
roleDefinitionId: roleDefinitionId
148+
principalId: principalId
149+
principalType: principalType
150+
}
151+
}
136152
```
153+
154+
# [ARM template](#tab/armtemplate)
155+
156+
```json
137157
{
138-
"type": "Microsoft.Authorization/roleAssignments",
139-
"apiVersion": "2018-09-01-preview",
140-
"name": "[guid(concat(resourceGroup().id, variables('resourceName'))]",
141-
"properties": {
142-
"roleDefinitionId": "[variables('roleDefinitionId')]",
143-
"principalId": "[variables('principalId')]"
144-
}
158+
"type": "Microsoft.Authorization/roleAssignments",
159+
"apiVersion": "2020-10-01-preview",
160+
"name": "[guid(resourceGroup().id, variables('principalId'), variables('roleDefinitionId'))]",
161+
"properties": {
162+
"roleDefinitionId": "[variables('roleDefinitionId')]",
163+
"principalId": "[variables('principalId')]",
164+
"principalType": "[variables('principalType')]"
165+
}
145166
}
146167
```
147168

169+
---
170+
171+
For more information, see [Create Azure RBAC resources by using Bicep](../azure-resource-manager/bicep/scenarios-rbac.md).
172+
148173
### Symptom - Role assignments with identity not found
149174

150175
In the list of role assignments for the Azure portal, you notice that the security principal (user, group, service principal, or managed identity) is listed as **Identity not found** with an **Unknown** type.
@@ -167,7 +192,7 @@ CanDelegate : False
167192

168193
Similarly, if you list this role assignment using Azure CLI, you might see an empty `principalName`. For example, [az role assignment list](/cli/azure/role/assignment#az-role-assignment-list) returns a role assignment that is similar to the following output:
169194

170-
```
195+
```json
171196
{
172197
"canDelegate": null,
173198
"id": "/subscriptions/11111111-1111-1111-1111-111111111111/providers/Microsoft.Authorization/roleAssignments/22222222-2222-2222-2222-222222222222",

0 commit comments

Comments
 (0)