Overview of Microsoft Graph permissions

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.

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.

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.

To learn more about how permissions work, watch the following video.

Permission types

Microsoft Graph supports two access scenarios, delegated access and app-only access. In delegated access, the app calls Microsoft Graph on behalf of a signed-in user. In app-only access, the app calls Microsoft Graph with its own identity, without a signed in user.

To support these access scenarios, Microsoft Graph exposes delegated permissions and application permissions.

Delegated permissions

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.

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:

• Tom created or owns the files.
• The files were shared directly with Tom, or indirectly shared with him through a team or group membership.
• Tom has been granted permissions through a role-based access control (RBAC) system such as Microsoft Entra RBAC.

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.

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 to identify delegated permissions that are valid for personal Microsoft accounts.

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.

Note

Permissions granted through Microsoft Entra built-in roles don't limit the app to calling Microsoft Graph APIs only.

Application permissions

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.

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.

Apart from being assigned Microsoft Graph application permissions, an app may also be granted the privileges it needs through one of the following conditions:

• When the app is assigned ownership of the resource that it intends to manage.
• When the app is assigned a Microsoft Entra built-in or custom administrative roles.

Note

Permissions granted through Microsoft Entra built-in roles don't limit the app to calling Microsoft Graph APIs only.

Comparison of delegated and application permissions

Category	Delegated permissions	Application permissions
Types of apps	Web app / Mobile / Single-page app (SPA)	Web / Daemon
Access context	Get access on behalf of a user	Get access without a user
Who can consent	Users can consent for their data Admins can consent for all users	Only admin can consent
Other names	Scopes OAuth2 permissions	App roles App-only permissions Direct access permissions
Result of consent	oAuth2PermissionGrant	appRoleAssignment
Supported signInAudience types	AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount PersonalMicrosoftAccount	AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount

The following image illustrates an app's privileges in delegated vs app-only access scenarios.

Permissions naming pattern

Microsoft Graph exposes granular permissions that help you control the access that apps have to Microsoft Graph resources, like users, groups, and mail. These permissions are named in the following pattern:

{resource}.{operation}.{constraint}

Value	Description	Examples
{resource}	Refers to a Microsoft Graph resource to which the permission allows access. For example, the user resource.	User, Application, or Group
{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
{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

Examples:

• User.Read - Allows the app to read information about the signed-in user.
• Application.ReadWrite.All - Allows the app to manage all applications in the tenant.
• Application.ReadWrite.OwnedBy - Allows the app to manage only the applications that it creates or owns.
• Group.Create - Allows the application create new groups, but not modify or delete them.
• Member.Read.Hidden - Allows the app to read hidden memberships

For the full list of permissions exposed by Microsoft Graph, see the Microsoft Graph permissions reference.

Limited information returned for inaccessible member objects

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.

This principle is applied to all relationships that are of directoryObject type. Examples include /groups/{id}/members, /users/{id}/memberOf or me/ownedObjects.

Example scenario

A group's members are users, groups, and devices. An app has been granted the Microsoft Graph User.Read.All and Group.Read.All permissions. The app calls the list group members API to retrieve the members of the group.

To read the basic properties of a group's members that are users, the app needs at least the User.Read.All permission. To read the basic properties of a group's members that are groups, the app needs at least the Group.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.

Because the app has permissions to access only user and group objects in the group, but not device objects, in the response:

• All the basic properties of the user and group member objects are returned.
• For the device member objects, only the object type and object ID are returned, but all other properties have the value null.

Example

Request

HTTP

GET https://graph.microsoft.com/v1.0/groups/{id}/members

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GetAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups members list --group-id {group-id}

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



members, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), nil)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DirectoryObjectCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let members = await client.api('/groups/{id}/members')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->get()->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupMember -GroupId $groupId

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.groups.by_group_id('group-id').members.get()

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Response

The following object is an example of the response:

{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
    "value":[
        {
            "@odata.type":"#microsoft.graph.user",
            "id":"69d035a3-29c9-469f-809d-d21a4ae69e65",
            "displayName":"Adele Vance",
            "createdDateTime":"2019-09-18T09:06:51Z",
        },
        {
            "@odata.type":"#microsoft.graph.group",
            "id":"c43a7cc9-2d95-44b6-bf6a-6392e41949b4",
            "displayName":"All Company",
            "description":null,
            "createdDateTime":"2019-10-24T01:34:35Z"
        },
        {
            "@odata.type":"#microsoft.graph.device",
            "id": "d282309e-f91d-43b6-badb-9e68aa4b4fc8",
            "accountEnabled":null,
            "deviceId":null,
            "displayName":null,
            "operatingSystem":null,
            "operatingSystemVersion":null
        }
    ]
}

Best practices for using Microsoft Graph permissions

Microsoft Graph exposes granular permissions that allow an app to request only the permissions it requires to function. Granular permissions allow you to apply the principle of least privilege when assigning and granting permissions to an app, by granting the app the minimum permission it needs for the operation.

Consider the following examples:

• An app needs to only read the profile information of the signed-in user. The app requires only the User.Read permission, which is the least privileged permission to access the signed-in user's information. Granting the app the User.ReadWrite permission makes it over-privileged because the app doesn't need to update the user's profile.
• An app needs to read the groups in the tenant without a signed-in user. The app requires only the Group.Read.All application permission, which is the least privileged permission to read groups in the tenant without a signed-in user.
• 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 the user's calendar data requires Calendars.Read, updating the calendar with scheduled jobs requires a higher privileged permission, Calendars.ReadWrite. In this case, the app should request Calendars.ReadWrite.

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.

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 and Building apps that secure identity through permissions and consent.

Limits on requested permissions per app

Microsoft Entra ID limits the number of permissions that can be requested and consented by a client app. These limits depend on the signInAudience value for an app, shown in the app's manifest.

signInAudience	Allowed users	Maximum permissions the app can request	Maximum Microsoft Graph permissions the app can request	Maximum permissions that can be consented in a single request
AzureADMyOrg	Users from the organization where the app is registered	400	400	About 155 delegated permissions and about 300 application permissions
AzureADMultipleOrgs	Users from any Microsoft Entra organization	400	400	About 155 delegated permissions and about 300 application permissions
PersonalMicrosoftAccount	Consumer users (such as Outlook.com or Live.com accounts)	30	30	30
AzureADandPersonalMicrosoftAccount	Consumer users and users from any Microsoft Entra organization	30	30	30

Retrieve permission IDs through Microsoft Graph

To set permissions using the Azure CLI, PowerShell, or infrastructure as code frameworks, you may need the identifier for the permission that you want to use instead of the name. The permissions reference lists IDs for all Microsoft Graph permissions. Alternatively, you can read information about all Microsoft Graph permissions programmatically through the Get servicePrincipal API in Microsoft Graph. The following example shows a request.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions

The appRoles, oauth2PermissionScopes, and resourceSpecificApplicationPermissions objects store the application, delegated, and resource-specific consent permissions respectively.

Related content

• Microsoft Graph permissions reference.
• Overview of role-based access control in Microsoft Entra ID.
• Understanding delegated access