Поделиться через

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

  • Статья

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

Примечание.

Разрешения, предоставляемые через 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.

    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 и т. д.
    • Однако в качестве альтернативы отдельным разрешениям уровня ресурсов приложению можно назначить по крайней мере разрешение Directory.Read.Allдля чтения всех свойств для всех типов элементов.

    Пример

    Запрос

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

    Отклик

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

    {
"@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 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 хранят разрешения на согласие приложения, делегированные и зависящие от ресурса соответственно.

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