You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: concepts/permissions-overview.md
+37-21Lines changed: 37 additions & 21 deletions
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,23 @@
1
1
---
2
2
title: "Overview of Microsoft Graph permissions"
3
-
description: "Microsoft Graph exposes granular permissions that help you control the access that apps have to Microsoft Graph resources, like users, groups, and mail. Learn more about working with Microsoft Graph permissions to allow your app to access your data securely."
3
+
description: "Learn more about working with Microsoft Graph permissions to allow your app to access your data securely."
#Customer-intent: As a developer integrating with Microsoft Graph, I want to learn about using Microsoft Graph permissions, so that I can properly request and manage permissions for my app.
12
+
13
+
#customer intent: As a developer integrating with Microsoft Graph, I want to learn about using Microsoft Graph permissions, so that I can properly request and manage permissions for my app.
13
14
---
14
15
15
16
# Overview of Microsoft Graph permissions
16
17
17
18
Before the Microsoft identity platform can authorize your app to access data in the Microsoft cloud, the app must be granted the privileges that it needs. Similarly, before the Microsoft identity platform can authorize your app to access data through Microsoft Graph, the app must be granted the privileges that it needs.
18
19
19
-
One way to grant an app the privileges it needs to access and work with your data through Microsoft Graph is by assigning it *Microsoft Graph permissions*.
20
+
One way to grant an app the privileges it needs to access and work with your data through Microsoft Graph is by assigning it *Microsoft Graph permissions*. Another way is through role-based access control (RBAC) systems, like [Microsoft Entra RBAC](/azure/active-directory/roles/custom-overview). In some cases, access to data through Microsoft Graph APIs might require both Microsoft Graph permissions and RBAC permissions.
20
21
21
22
This article introduces Microsoft Graph permissions and provides guidance for using them. To see the full list of permissions that Microsoft Graph exposes, see the [Microsoft Graph permissions reference](permissions-reference.md).
22
23
@@ -32,17 +33,17 @@ To support these access scenarios, Microsoft Graph exposes *delegated permission
32
33
33
34
### Delegated permissions
34
35
35
-
*Delegated permissions*, also called *scopes*, are used in the delegated access scenario. They're permissions that allow the application to act on behalf of a signed-in user. However, the application will never be able to access anything the signed-in user couldn't access.
36
+
*Delegated permissions*, also called *scopes*, are used in the delegated access scenario. They're permissions that allow the application to act on behalf of a signed-in user. However, the application can't access anything the signed-in user couldn't access.
36
37
37
-
For example, an application has been granted the *Files.Read.All* delegated permission on behalf of Tom, a user. The application will only be able to read all files in the organization that Tom can already access. Tom may be able to access the files because he has permissions through one of the following ways:
38
+
For example, an application has been granted the *Files.Read.All* delegated permission on behalf of Tom, a user. The application can only read all files in the organization that Tom can already access. Tom may be able to access the files because he has permissions through one of the following ways:
38
39
39
40
- Tom created or owns the files.
40
-
- The files were shared directly with Tom, or indirectly shared with him through a team or group membership.
41
-
- Tom has been granted permissions through a role-based access control (RBAC) system such as [Microsoft Entra RBAC](/azure/active-directory/roles/custom-overview).
41
+
- The files were shared directly with Tom, or indirectly shared through a team or group membership.
42
+
- Tom has been granted permissions through a supported RBAC system.
42
43
43
-
Therefore, in a delegated scenario, the privileges that an app has to act on behalf of a user is determined by the Microsoft Graph permissions that the app has been granted *and* the user's own permissions.
44
+
**Therefore, in a delegated scenario, the privileges that an app has to act on behalf of a user is determined by the Microsoft Graph permissions that the app has been granted *and* the user's own permissions.**
44
45
45
-
In a delegated access scenario, an app may allow users to sign in with their personal Microsoft accounts, like Outlook.com, work or school accounts, or allow both account types. All delegated permissions are valid for work or school accounts, but not all are valid for personal Microsoft accounts. Use the [Microsoft Graph permissions reference](permissions-reference.md) to identify delegated permissions that are valid for personal Microsoft accounts.
46
+
In a delegated access scenario, an app might allow users to sign in with their personal Microsoft accounts, like Outlook.com, work or school accounts, or allow both account types. All delegated permissions are valid for work or school accounts, but not all are valid for personal Microsoft accounts. Use the [Microsoft Graph permissions reference](permissions-reference.md) to identify delegated permissions that are valid for personal Microsoft accounts.
46
47
47
48
When a user signs in to an app they, or, in some cases, an administrator, are given a chance to consent to the delegated permissions. If they grant consent, the app can access resources and APIs within the boundaries of the user's permissions.
48
49
@@ -51,14 +52,14 @@ When a user signs in to an app they, or, in some cases, an administrator, are gi
51
52
52
53
### Application permissions
53
54
54
-
*Application permissions*, also called *app roles*, are used in the app-only access scenario, without a signed-in user present. The application will be able to access any data that the permission is associated with. For example, an application granted the *Files.Read.All* application permission will be able to read any file in the organization.
55
+
*Application permissions*, also called *app roles*, are used in the app-only access scenario, without a signed-in user present. The application is able to access *any* data that the permission is associated with. For example, an application granted the *Files.Read.All* application permission can read any file in the organization.
55
56
56
-
For apps that access resources and APIs without a signed-in user, the application permissions can be consented to by an administrator when the app is installed in the tenant or through the Microsoft Entra admin center. Only an administrator can consent to application permissions.
57
+
For apps that access resources and APIs without a signed-in user, an administrator consents to the application permissions when the app is installed in the tenant or through the Microsoft Entra admin center. Only Privileged Role Administrator and Global Administrator can consent to application permissions.
57
58
58
59
Apart from being assigned Microsoft Graph application permissions, an app may also be granted the privileges it needs through one of the following conditions:
59
60
60
61
- When the app is assigned ownership of the resource that it intends to manage.
61
-
- When the app is assigned a Microsoft Entra built-in or custom administrative roles.
62
+
- When the app is assigned permissions through an RBAC system or custom administrative roles.
62
63
63
64
> [!NOTE]
64
65
> Permissions granted through [Microsoft Entra built-in roles](/entra/identity/role-based-access-control/permissions-reference?toc=/graph/toc.json) don't limit the app to calling Microsoft Graph APIs only.
@@ -71,7 +72,7 @@ Apart from being assigned Microsoft Graph application permissions, an app may al
71
72
| Access context |[Get access on behalf of a user](auth-v2-user.md)|[Get access without a user](auth-v2-service.md)|
72
73
| Who can consent | <li> Users can consent for their data <li> Admins can consent for all users | Only admin can consent |
| Result of consent |[oAuth2PermissionGrant](/graph/api/resources/oauth2permissiongrant)|[appRoleAssignment](/graph/api/resources/approleassignment)|
75
+
| Result of consent |[oAuth2PermissionGrant](/graph/api/resources/oauth2permissiongrant)object|[appRoleAssignment](/graph/api/resources/approleassignment) object|
|`{resource}`| Refers to a Microsoft Graph resource to which the permission allows access. For example, the `user` resource. |`User`, `Application`, or `Group`|
90
-
|`{operation}`| Refers to the Microsoft Graph API operations that are allowed on the data that's exposed by the resource. For example, `Read` for read operations only, or `ReadWrite` for read, create, update, and delete operations. |`Read`, `ReadBasic`, `ReadWrite`, `Create`, `Manage`, or `Migrate`|
91
-
|`{constraint}`| Determines the potential extent of access an app will have within the directory. This value may not be explicitly declared. When undeclared, the default constraint is limited to data that's owned by the signed-in user. |`All`, `AppFolder`, `OwnedBy`, `Selected`, `Shared`, `Hidden`|
91
+
|`{operation}`| Refers to the Microsoft Graph API operations that are allowed on the data that's exposed by the resource. For example, `Read` for read operations only, or `ReadWrite` for read, create, update, and delete operations. |`Read`, `ReadBasic`, `ReadWrite`, `Create`, `Manage`, or `Migrate`|
92
+
|`{constraint}`| Determines the potential extent of access an app has within the directory. This value may not be explicitly declared. When undeclared, the default constraint is limited to data that's owned by the signed-in user. |`All`, `AppFolder`, `OwnedBy`, `Selected`, `Shared`, `Hidden`|
92
93
93
94
Examples:
94
95
-*User.Read* - Allows the app to read information about the signed-in user.
@@ -99,15 +100,23 @@ Examples:
99
100
100
101
For the full list of permissions exposed by Microsoft Graph, see the [Microsoft Graph permissions reference](permissions-reference.md).
101
102
103
+
## Resource-specific consent (RSC) permissions
104
+
105
+
RSC is an authorization framework that allows for granting scoped access to the data exposed by a resource. Through RSC, an authorized user can give an app access to the data of a specific instance of a resource type. They don't need to give app access to every instance of the resource type in the entire tenant.
106
+
107
+
RSC permissions are also available for consent and are supported by only a subset of features available through Microsoft Graph such as Teams, chats, and messages. Learn more about [RSC permissions](/microsoftteams/platform/graph-api/rsc/resource-specific-consent) or discover the [full list of RSC permissions available](./permissions-reference.md#resource-specific-consent-rsc-permissions).
108
+
102
109
## Limited information returned for inaccessible member objects
103
110
104
111
Container objects such as groups support members of various types, for example users and devices. When an application with the right privileges queries the membership of a container object, it receives a `200 OK` response and a collection of objects. However, if the app doesn't have the permissions to read a certain object type in the container, objects of that type are returned but with limited information, for example, only the object type and ID may be returned and other properties are indicated as `null`. Complete information is returned for the object types that the app has permissions to read.
105
112
106
-
This principle is applied to all relationships that are of [directoryObject](/graph/api/resources/directoryobject) type. Examples include `/groups/{id}/members`, `/users/{id}/memberOf` or`me/ownedObjects`.
113
+
This principle is applied to all relationships that are of [directoryObject](/graph/api/resources/directoryobject) type. Examples include `/groups/{id}/members`, `/users/{id}/memberOf`, and`me/ownedObjects`.
107
114
108
-
For example, a group can have users, groups, applications, service principals, devices, and contacts as members. An app is granted the *GroupMember.Read.All* least privileged permission to [List group members](/graph/api/group-list-members). In the response object, only the **id** and **@odata.type** properties are populated for all the members that are returned. The other properties are indicated as `null`.
109
-
110
-
To read the basic properties of a group's members that are users, the app needs at least the *User.ReadBasic.All* permission. To read the basic properties of a group's members that are groups, the app needs at least the *GroupMember.Read.All* permission. To read the basic properties of a group's members that are devices, the app needs at least the *Device.Read.All* permission, and so on. However, as an alternative to the individual resource-level permissions, the app can be assigned at least the *Directory.Read.All* permission to read *all properties for all member types*.
115
+
For example, a group can have users, groups, applications, service principals, devices, and contacts as members. An app is granted the *GroupMember.Read.All* least privileged permission to [List group members](/graph/api/group-list-members). In the response object, only the **id** and **@odata.type** properties are populated for all the members that are returned. The other properties are indicated as `null`. For this API:
116
+
- To read the basic properties of a group's members that are users, the app needs at least the *User.ReadBasic.All* permission.
117
+
- To read the basic properties of a group's members that are groups, the app needs at least the *GroupMember.Read.All* permission.
118
+
- To read the basic properties of a group's members that are devices, the app needs at least the *Device.Read.All* permission, and so on.
119
+
- However, as an alternative to the individual resource-level permissions, the app can be assigned at least the *Directory.Read.All* permission to read *all properties for all member types*.
111
120
112
121
### Example
113
122
@@ -199,10 +208,17 @@ Consider the following examples:
199
208
- An app needs to read the groups in the tenant without a signed-in user. The app requires only the *GroupMember.Read.All* application permission, which is the least privileged permission to read groups in the tenant without a signed-in user.
200
209
- An app needs to read or write to a calendar of the signed-in user. The app manages dynamic jobs, and syncs from the user's Outlook calendar to keep the app up-to-date so to schedule jobs for the user. Even though [getting](/graph/api/event-delta) the user's calendar data requires *Calendars.Read*, [updating](/graph/api/user-post-events) the calendar with scheduled jobs requires a higher privileged permission, *Calendars.ReadWrite*. In this case, the app should request *Calendars.ReadWrite*.
201
210
202
-
Granting an application more privileges than it needs is a poor security practice that exposes an app to unauthorized and unintended access to data or operations. Also, requesting more permissions than necessary may cause users to refrain from consenting to an app, affecting an app's adoption and usage.
211
+
Granting an application more privileges than it needs is a poor security practice that increases the app's attack surface and exposes it to unauthorized and unintended access to data or operations. Also, requesting more permissions than necessary may cause users to refrain from consenting to an app, affecting an app's adoption and usage.
203
212
204
213
Apply the principle of least privilege when assigning and granting Microsoft Graph permissions to an app. For more information, see [Enhance security with the principle of least privilege](/azure/active-directory/develop/secure-least-privileged-access) and [Building apps that secure identity through permissions and consent](/security/zero-trust/develop/identity).
205
214
215
+
### Permissions to use with caution
216
+
217
+
Some Microsoft Graph permissions grant access to a wider range of data or operations than others. Use such permissions with caution. For example, the *Directory.AccessAsUser.All* permission is the highest privileged delegated permission that grants access to nearly all API operations across Microsoft Entra ID. *Directory.ReadWrite.All* permission is second in privilege ranking. *Directory.Read.All* is the highest privileged read-only permission for Microsoft Entra ID resources. These permissions should be used with caution and only when necessary. Always use lesser-privileged options permissions instead.
218
+
219
+
In API reference documentation relating to Microsoft Entra ID resources, some of these higher privileged permissions might be intentionally excluded from the table of permissions supported to access the API.
220
+
221
+
In addition, the Global Administrator role is the highest privileged built-in role in Microsoft Entra ID. In API reference documentation, this role is intentionally excluded from the list of roles supported to access the API in favor of lesser-privileged roles.
0 commit comments