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

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

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

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

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

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

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

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

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

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

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

• Том создал или владеет файлами.
• Файлы были переданы непосредственно Тому или косвенно переданы ему через членство в команде или группе.
• Тому были предоставлены разрешения через систему управления доступом на основе ролей (RBAC), например Microsoft Entra RBAC.

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

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

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

Примечание.

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

{resource}. {operation}. {constraint}

Значение	Описание	Примеры
{resource}	Относится к ресурсу Microsoft Graph, доступ к которому разрешает разрешение. Например, user ресурс.	User, Application или Group
{operation}	Относится к операциям Microsoft API Graph, которые разрешены для данных, предоставляемых ресурсом. Например, Read для операций чтения или ReadWrite для операций чтения, создания, обновления и удаления.	Read, ReadBasic, ReadWrite, Create, Manageили 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.

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

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

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

Пример сценария

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

Чтобы прочитать основные свойства членов группы, которые являются пользователями, приложению требуется по крайней мере разрешение User.Read.All . Чтобы прочитать основные свойства членов группы, которые являются группами, приложению требуется по крайней мере разрешение Group.Read.All . Чтобы считывать основные свойства членов группы, которые являются устройствами, приложению требуется по крайней мере разрешение Device.Read.All .

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

• Возвращаются все основные свойства объектов-членов пользователя и группы.
• Для объектов-членов устройства возвращаются только тип объекта и идентификатор объекта, но все остальные свойства имеют значение NULL.

Пример

Запрос

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.

CLI

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

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

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)

Дополнительные сведения о добавлении пакета 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

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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 делает его более привилегированным, так как приложению не нужно обновлять профиль пользователя.
• Приложению необходимо считывать группы в клиенте без вошедшего пользователя. Приложению требуется только разрешение приложения Group.Read.All , которое является наименее привилегированным разрешением на чтение групп в клиенте без вошедшего пользователя.
• Приложению необходимо читать или записывать данные в календарь пользователя, выполнившего вход. Приложение управляет динамическими заданиями и синхронизируется из календаря Outlook пользователя, чтобы поддерживать приложение в актуальном состоянии, чтобы запланировать задания для пользователя. Несмотря на то, что для получения данных календаря пользователя требуется Calendars.Read, для обновления календаря с запланированными заданиями требуется более высокое разрешение Calendars.ReadWrite. В этом случае приложение должно запрашивать Calendars.ReadWrite.

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

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

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

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 Graph

Чтобы задать разрешения с помощью Azure CLI, 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.
• Основные сведения о делегировании доступа