Обзор разрешений Microsoft Graph

Прежде чем платформа удостоверений Майкрософт сможет авторизовать ваше приложение для доступа к данным в облаке Microsoft, вы должны предоставить приложению необходимые привилегии. Аналогичным образом, прежде чем платформа удостоверений Майкрософт сможет авторизовать ваше приложение для доступа к данным через Microsoft Graph, вы должны предоставить приложению необходимые привилегии.

Один из способов предоставить приложению привилегии, необходимые для доступа к вашим данным и работы с ними через Microsoft Graph, — назначить приложению разрешения Microsoft Graph. Другой способ — через системы управления доступом на основе ролей (RBAC), такие как Microsoft Entra RBAC. В некоторых случаях для доступа к данным через API Microsoft Graph могут потребоваться разрешения как Microsoft Graph, так и разрешения RBAC.

В этой статье представлены разрешения Microsoft Graph и рекомендации по их использованию. Полный список разрешений, предоставляемых Microsoft Graph, см. в справочнике по разрешениям Microsoft Graph.

Чтобы узнать больше о том, как работают разрешения, посмотрите следующее видео.

Типы разрешений

Microsoft Graph поддерживает два сценария доступа: делегированный доступ и доступ только для приложений. При делегированном доступе приложение вызывает Microsoft Graph от имени вошедшего пользователя. При доступе только для приложения приложение вызывает Microsoft Graph со своим собственным удостоверением, без вошедшего пользователя.

Для поддержки этих сценариев доступа Microsoft Graph предоставляет делегированные разрешения и разрешения приложений.

Делегированные разрешения

Делегированные разрешения, также называемые областями, работают в сценарии делегированного доступа. Эти разрешения позволяют приложению действовать от имени вошедшего пользователя. Однако приложение не может получить доступ ни к чему, к чему не смог получить доступ вошедший в систему пользователь.

Например, приложение получает Files. Делегированное разрешение Read.All от имени пользователя Тома. Приложение может читать только все файлы в организации, к которым у Марта уже есть доступ. Том может получить доступ к файлам, так как у него есть разрешения, одним из следующих способов:

• Том создал файлы или является их владельцем.
• Файлы передавались непосредственно Тому или косвенно через членство в команде или группе.
• Тому предоставлены разрешения через поддерживаемую систему RBAC.

Поэтому в делегированном сценарии привилегии, которые приложение должно действовать от имени пользователя, определяются разрешениями Microsoft Graph, предоставленными приложению, и собственными разрешениями пользователя.

В сценарии делегированного доступа приложение может позволить пользователям входить в свои личные учетные записи Майкрософт, например Outlook.com, рабочие или учебные учетные записи, или оба типа учетных записей. Все делегированные разрешения действуют для рабочих или учебных учетных записей, но не все из них действительны для личных учетных записей Майкрософт. Используйте справочник по разрешениям Microsoft Graph для определения делегированных разрешений, действительных для личных учетных записей Майкрософт.

При входе пользователя в приложение он или, в некоторых случаях, администратор получает возможность согласиться на делегированные разрешения. Если он предоставит согласие, приложение сможет получать доступ к ресурсам и API в пределах границ разрешений пользователя.

Примечание.

Разрешения, предоставляемые с помощью встроенных ролей Microsoft Entra, не ограничивают приложение вызовом только API Microsoft Graph.

Разрешения приложений

Разрешения приложений, также называемые ролями приложений, работают в сценарии доступа только к приложению, без присутствия пользователя, вошедшего в систему. Приложение может получить доступ к любым данным, с которыми связано разрешение. Например, приложение предоставило Files. Чтение.Все разрешения приложения могут читать любой файл в организации.

При наличии разрешения приложения User.ReadWrite.All приложение может обновлять многие доступные для записи свойства пользователей, поддерживаемые Microsoft Graph, в том числе для пользователей, которым назначены привилегированные роли администратора.

Разрешения приложений являются высокопривилегированными, поскольку они позволяют приложениям получать доступ к ресурсам и изменять их, не требуя участия пользователя, вошедшего в систему. С точки зрения делегированных разрешений рекомендуется использовать модель делегированных разрешений, если она соответствует требованиям приложения.

Для приложений, которые обращаются к ресурсам и API без вошедшего в систему пользователя, администратор дает согласие на разрешения приложения, когда приложение установлено в клиенте или через Центр администрирования Microsoft Entra. Только администратор привилегированной роли и глобальный администратор могут дать согласие на использование разрешений приложению.

Приложению могут быть назначены не только разрешения Microsoft Graph, но и необходимые привилегии при выполнении одного из следующих условий:

• Когда приложению назначено право собственности на ресурс, которым оно намерено управлять.
• Когда приложению назначены разрешения через систему RBAC или настраиваемые административные роли.

Примечание.

Разрешения, предоставляемые с помощью встроенных ролей Microsoft Entra, не ограничивают приложение вызовом только API Microsoft Graph.

Сравнение делегированных разрешений и разрешений приложения

Категория	Делегированные разрешения	Разрешения приложений
Типы приложений	Веб-приложение, мобильные устройства и одностраничные приложения	Веб-приложение / управляющая программа
Контекст доступа	Получение доступа от имени пользователя	Получение доступа без пользователя
Кто может дать согласие	Пользователи могут дать согласие, связанное с их данными Администраторы могут дать согласие для всех пользователей Доступность согласия пользователя также зависит от политик согласия приложения вашего клиента. Даже если для разрешения по умолчанию не требуется согласие администратора, политики вашей организации все равно могут ограничивать согласие пользователей	Дать согласие может только администратор
Другие имена	Scopes Разрешения OAuth2	Роли приложений Разрешения только для приложения Разрешения на прямой доступ
Результат согласия	Объект oAuth2PermissionGrant	Объект appRoleAssignment
Поддерживаемые типы signInAudience	AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount PersonalMicrosoftAccount	AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount

На следующем рисунке показаны привилегии приложения в сценариях делегированного доступа и доступа только для приложений.

Рекомендации по выбору типов разрешений для регистрации агента соединителя

Агенты соединителя Microsoft Graph работают в качестве фоновых служб и требуют разрешений приложения Microsoft Graph.

Делегированные разрешения не поддерживаются для регистрации агента соединителя и вызывают сбои регистрации, даже если разрешения выглядят правильно настроенными.

Запросите разрешения приложения с минимальными привилегиями , необходимые для вашего сценария соединителя, и убедитесь, что пользователю предоставлено согласие администратора на уровне клиента .

Шаблон именования разрешений

Microsoft Graph предоставляет детализированные разрешения, позволяющие управлять доступом приложений к ресурсам Microsoft Graph, таким как пользователи, группы и почта. Эти разрешения соответствуют шаблону именования:

{resource}. {операция}. {constraint}

Значение	Описание	Примеры
{resource}	Ссылается на ресурс Microsoft Graph, доступ к которому предоставляется в соответствии с разрешением. Например, user ресурс.	User, Application или Group
{operation}	Относится к операциям Microsoft API Graph, которые разрешены с данными, предоставляемыми ресурсом. Например, Read только для операций чтения или ReadWrite для операций чтения, создания, обновления и удаления.	Read, , ReadBasic, ReadWrite, ManageCreate, илиMigrate
{constraint}	Определяет потенциальную степень доступа приложения к каталогу. Это значение может не быть объявлено явно. Если параметр не объявлен, ограничение по умолчанию ограничено данными, принадлежащими вошедшему пользователю.	All, AppFolder, OwnedBy, Selected, Shared, Hidden

Примеры:

• User.Read — разрешает приложению читать сведения о вошедшем в систему пользователе.
• Application.ReadWrite.All — позволяет приложению управлять всеми приложениями в клиенте.
• Application.ReadWrite.OwnedBy — позволяет приложению управлять только теми приложениями, которые оно создает или которыми владеет.
• Group.Create — позволяет приложению создавать новые группы, но не изменять и удалять их.
• Member.Read.Hidden — позволяет приложению читать скрытые членства.

Полный список разрешений, предоставляемых Microsoft Graph, см. в справочнике по разрешениям Microsoft Graph.

Разрешения для конкретных ресурсов (RSC)

RSC — это платформа авторизации, предоставляющая ограниченный доступ к данным, предоставляемым ресурсом. Через RSC авторизованный пользователь может предоставить приложению доступ к данным определенного экземпляра ресурса. Им не нужно предоставлять приложению доступ ко всем экземплярам этого типа ресурса во всем клиенте.

Разрешения RSC также доступны для согласия и поддерживаются только подмножеством функций, доступных через Microsoft Graph, таких как Teams, чаты и сообщения. Дополнительные сведения см. в разрешениях RSC и полном списке доступных разрешений RSC.

Ограниченные сведения, возвращаемые для недоступных объектов member

Объекты контейнеров, такие как группы, поддерживают участников различных типов, например пользователей и устройства. Когда приложение с соответствующими привилегиями запрашивает членство объекта-контейнера, оно получает 200 OK ответ и коллекцию объектов. Если же у приложения нет разрешений на чтение определенного типа объектов в контейнере, оно получает объекты этого типа, но с ограниченной информацией. Например, могут быть возвращены только тип и идентификатор объекта, а другие свойства указаны как null. Приложение получает полные сведения о типах объектов, на чтение которых у него есть разрешения.

Этот принцип применяется ко всем связям типа directoryObject . Примеры: , /groups/{id}/members/users/{id}/memberOfи me/ownedObjects.

Например, участниками группы могут быть пользователи, группы, приложения, субъекты-службы, устройства и контакты. Приложению предоставляется разрешение GroupMember.Read.All с наименьшими правами на перечисление участников группы. В объекте отклика заполняются только свойства id и @odata.type для всех возвращаемых членов. Другие свойства указаны как null. Для этого API и для возврата дополнительных сведений для участников группы приложению необходимы следующие дополнительные разрешения:

• Для чтения основных свойств участников группы, являющихся пользователями, User.ReadBasic.All является разрешением с наименьшими привилегиями.
• Для чтения основных свойств участников группы, которые являются группами, GroupMember.Read.All является разрешением с наименьшими привилегиями.
• Для чтения основных свойств участников группы, являющихся устройствами, Device.Read.All является разрешением с наименьшими привилегиями.
• Для чтения основных свойств участников группы, являющихся субъектами-службами, Application.Read.All является разрешением с наименьшими привилегиями.
• В соответствии с принципом предоставления минимальных привилегий используйте указанные выше разрешения в соответствии с вашим приложением. однако в качестве альтернативы отдельным разрешениям на уровне ресурсов назначьте приложению разрешение Directory.Read.All на чтение всех свойств для всех типов элементов.

Пример

Запрос

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();

Подробные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по SDK.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

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


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
members, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), nil)

Подробные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по SDK.

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();

Подробные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

Подробные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

Подробные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupMember -GroupId $groupId

Подробные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по SDK.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

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

Подробные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по SDK.

Отклик

Следующий объект является примером ответа:

{
"@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
        }
    ]
}

Рекомендации по использованию разрешений Microsoft Graph

Microsoft Graph предоставляет детализированные разрешения, позволяющие приложению запрашивать только те разрешения, которые необходимы для его работы. Детализированные разрешения позволяют применять принцип минимальных привилегий при назначении и предоставлении приложению разрешений. Предоставьте приложению минимальное разрешение, необходимое для выполнения операции.

Рассмотрим следующие примеры.

• Приложению необходимо читать сведения профиля вошедшего пользователя. Приложению требуется только разрешение User.Read , которое является наименее привилегированным разрешением для доступа к данным вошедшего пользователя. Предоставление приложению разрешения User.ReadWrite делает его сверхпривилегированным, так как приложению не нужно обновлять профиль пользователя.
• Приложению необходимо читать группы в клиенте без вошедшего пользователя. Приложению требуется только разрешение приложения GroupMember.Read.All , которое является наименее привилегированным разрешением на чтение групп в клиенте без вошедшего пользователя.
• Приложению необходимо читать или записывать данные в календарь пользователя, вошедшего в систему. Приложение управляет динамическими заданиями и синхронизирует их с календарем Outlook пользователя, чтобы поддерживать актуальность приложения и планировать задания для пользователя. Несмотря на то, что для получения данных календаря пользователя требуется свойство Calendars.Read, для обновления календаря с использованием запланированных заданий требуется разрешение с более высоким уровнем привилегий — Calendars.ReadWrite. В этом случае приложение должно запросить Calendars.ReadWrite.

Предоставление приложению большего количества привилегий, чем ему нужно, является плохой практикой обеспечения безопасности. Это повышает подверженность приложения несанкционированному и непреднамеренному доступу к данным или операциям. Кроме того, запрос большего количества разрешений, чем необходимо, может привести к тому, что пользователи воздержатся от согласия на использование приложения, что повлияет на принятие и использование приложения.

Применяйте принцип минимальных привилегий при назначении и предоставлении приложению разрешений Microsoft Graph. Дополнительные сведения см. в статьях "Повышение безопасности с помощью принципа минимальных привилегий" и "Создание приложений, обеспечивающих безопасность удостоверений с помощью разрешений и согласия".

Разрешения для осторожного использования

Некоторые разрешения Microsoft Graph предоставляют доступ к более широкому спектру данных или операций, чем другие. Используйте эти разрешения с осторожностью. Например, разрешение Directory.AccessAsUser.All — это делегированное разрешение с наивысшими правами доступа, предоставляющее доступ практически ко всем операциям API в Microsoft Entra ID. Разрешение Directory.ReadWrite.All занимает второе место в рейтинге привилегий. Directory.Read.All — это самое высокое разрешение только на чтение для ресурсов Microsoft Entra ID. Используйте эти разрешения с осторожностью и только при необходимости. Вместо этого всегда используйте разрешения для параметров с меньшими привилегиями.

В справочной документации по API, относящейся к ресурсам Microsoft Entra ID, некоторые из этих разрешений с более высоким уровнем привилегий могут быть намеренно исключены из таблицы разрешений, поддерживаемых для доступа к API.

Кроме того, роль глобального администратора является встроенной ролью с наивысшими правами в Microsoft Entra ID. В справочной документации по API эта роль намеренно исключена из списка ролей, поддерживающих доступ к API в пользу ролей с меньшими привилегиями.

Ограничения на запрашиваемые разрешения на приложение

Microsoft Entra ID ограничивает количество разрешений, которые могут быть запрошены клиентским приложением и согласованы. Эти ограничения зависят от signInAudience значения для приложения, указанного в манифесте приложения.

signInAudience	Разрешенные пользователи	Максимальное количество разрешений, которое может запросить приложение	Максимальное количество разрешений Microsoft Graph, которые может запросить приложение	Максимальное количество разрешений, которые можно дать в одном запросе
AzureADMyOrg	Пользователи из организации, в которой зарегистрировано приложение	400	400	Около 155 делегированных разрешений и около 300 разрешений приложения
AzureADMultipleOrgs	Пользователи из любой организации Microsoft Entra	400	400	Около 155 делегированных разрешений и около 300 разрешений приложения
PersonalMicrosoftAccount	Пользователи-потребители (например, учетные записи Outlook.com или Live.com)	30	30	30
AzureADandPersonalMicrosoftAccount	Пользователи и пользователи из любой организации Microsoft Entra	30	30	30

Примечание.

Для Microsoft Entra ID для агентов некоторые разрешения Microsoft Graph с высоким риском заблокированы для агентов по всему миру и не могут быть предоставлены удостоверениям агентов.

Если в коллекцию requiredResourceAccess записи включена заблокированная область делегированных разрешений Microsoft Graph или роль resourceAccess приложения, запрос отклоняется, сопровождается HTTP-ответом 400 Bad Request и ошибкой, указывающей, что разрешение заблокировано и не может быть предоставлено удостоверениям агента.

Список заблокированных разрешений Microsoft Graph для агентов см. в статье Разрешения Microsoft Graph, заблокированные для агентов.

Получение идентификаторов разрешений с помощью Microsoft Graph

Чтобы задать разрешения с помощью интерфейса командной строки Azure, PowerShell или платформ "инфраструктура как код", может потребоваться идентификатор разрешения, которое вы хотите использовать, вместо имени. В справочнике по разрешениям перечислены идентификаторы всех разрешений Microsoft Graph. Кроме того, сведения обо всех разрешениях Microsoft Graph можно прочитать программным способом с помощью API Get servicePrincipal в Microsoft Graph. Ниже показан пример запроса.

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

Объекты appRoles, oauth2PermissionScopes и resourceSpecificApplicationPermissions хранят разрешения на применение, делегированное согласие и разрешения для конкретных ресурсов соответственно.

Связанные материалы

• Справочник по разрешениям Microsoft Graph.
• Обзор управления доступом на основе ролей в Microsoft Entra ID.
• Общее представление о делегированном доступе