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


Предоставление или отзыв разрешений API программным способом

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

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

Предостережение

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

Предварительные условия

Чтобы выполнить эти инструкции, вам потребуется:

  • Клиент Microsoft Entra.
  • Выполнение запросов, приведенных в этой статье, в делегированном контексте. Выполните следующие действия.
    • Войдите в клиент API, например Graph Обозреватель как пользователь с правами на создание приложений в клиенте. Привилегии для создания разрешений можно ограничить или контролировать в клиенте с помощью политик согласия приложений, настроенных администратором.
    • В приложении, в которое вы выполнили вход, дайте согласие на делегированные разрешения Application.Read.All и AppRoleAssignment.ReadWrite.All для вошедшего пользователя. Вам не нужно давать согласие от имени вашей организации.
  • Получите идентификатор объекта субъекта-службы клиента, которому предоставляются роли приложения. В этой статье субъект-служба клиента определяется по идентификатору b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. В Центр администрирования Microsoft Entra разверните узелПриложения>удостоверений>Корпоративные приложения>Приложения, чтобы найти субъект-службу клиента. Выберите его и на странице Обзор скопируйте значение Идентификатор объекта.

Предостережение

Только соответствующие пользователи должны получать доступ к приложениям, которым предоставлено разрешение AppRoleAssignment.ReadWrite.All .

Шаг 1. Получение ролей приложения субъекта-службы ресурсов

Сначала найдите роли приложения, предоставляемые субъектом-службой ресурсов. Роли приложения определяются в объекте appRoles субъекта-службы. В этой статье субъект-служба Microsoft Graph используется в клиенте в качестве субъекта-службы ресурса.

Запрос

Следующий запрос извлекает роли приложения, определенные субъектом-службой Microsoft Graph в клиенте.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,appRoles

Отклик

Ниже показан пример отклика.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,appRoles)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "appRoles": [
                {
                    "allowedMemberTypes": [
                        "Application"
                    ],
                    "description": "Allows the app to read user profiles without a signed in user.",
                    "displayName": "Read all users' full profiles",
                    "id": "df021288-bdef-4463-88db-98f22de89214",
                    "isEnabled": true,
                    "origin": "Application",
                    "value": "User.Read.All"
                }
            ]
        }
    ]
}

Шаг 2. Предоставление роли приложения субъекту-службе клиента

На этом шаге предоставьте приложению роль приложения, которую предоставляет Microsoft Graph, что приведет к назначению роли приложения. На шаге 1 идентификатор объекта Microsoft Graph — 7ea9e944-71ce-443d-811c-71e8047b557a, а роль User.Read.All приложения определяется идентификатором df021288-bdef-4463-88db-98f22de89214.

Запрос

Следующий запрос предоставляет клиентскому приложению (субъекту id b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94) роль приложения с идентификатором df021288-bdef-4463-88db-98f22de89214 , который предоставляется субъектом-службой ресурсов с идентификатором 7ea9e944-71ce-443d-811c-71e8047b557a.

Примечание.

Если вы используете пакет SDK для Python, импортируйте следующие библиотеки:

from msgraph.generated.models.app_role_assignment import AppRoleAssignment
from msgraph.generated.models.service_principal import ServicePrincipal
POST https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo
Content-Type: application/json

{
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214"
}

Отклик

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo/$entity",
    "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
    "deletedDateTime": null,
    "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
    "createdDateTime": "2022-05-18T15:37:21.8215423Z",
    "principalDisplayName": "My application",
    "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "principalType": "ServicePrincipal",
    "resourceDisplayName": "Microsoft Graph",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
}

Подтверждение назначения роли приложения

Проверьте субъекты с назначениями ролей субъекту-службе ресурсов, выполнив следующий запрос.

Запрос

GET https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo

Отклик

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

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('7ea9e944-71ce-443d-811c-71e8047b557a')/appRoleAssignedTo",
    "value": [
        {
            "id": "47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M",
            "deletedDateTime": null,
            "appRoleId": "df021288-bdef-4463-88db-98f22de89214",
            "createdDateTime": "2022-05-18T15:37:21.8997216Z",
            "principalDisplayName": "My application",
            "principalId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "principalType": "ServicePrincipal",
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a"
        }
    ]
}

Шаг 3. Отзыв назначения роли приложения из субъекта-службы клиента

Запрос

DELETE https://graph.microsoft.com/v1.0/servicePrincipals/7ea9e944-71ce-443d-811c-71e8047b557a/appRoleAssignedTo/47nZsM8O_UuNq5Jz3QValCxBBiqJea9Drc9CMK4Ru_M

Отклик

HTTP/1.1 204 No Content

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

Предостережение

Будьте осторожны! Разрешения, предоставляемые программным способом, не подлежат проверке или подтверждению. Они вступают в силу немедленно.

Предварительные условия

Чтобы выполнить эти инструкции, вам потребуется:

  • Допустимый клиент Microsoft Entra.
  • Выполнение запросов, приведенных в этой статье, от имени пользователя. Выполните следующие действия.
    • Войдите в клиент API, например Graph Обозреватель, как пользователь с ролью администратора облачных приложений Microsoft Entra. Эта роль является наименее привилегированной для создания приложений и предоставления согласия делегированным разрешениям в клиенте. Привилегии для создания разрешений можно ограничить или контролировать в клиенте с помощью политик согласия приложений, настроенных администратором.
    • В приложении, в которое вы выполнили вход, даете согласие на делегированные разрешения Application.Read.All и DelegatedPermissionGrant.ReadWrite.All для вошедшего пользователя. Вам не нужно давать согласие от имени вашей организации.
    • Получите идентификатор объекта субъекта-службы клиента, которому вы предоставляете делегированные разрешения от имени пользователя. В этой статье субъект-служба клиента определяется по идентификатору b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. В Центр администрирования Microsoft Entra разверните узелПриложения>удостоверений>Корпоративные приложения>Приложения, чтобы найти субъект-службу клиента. Выберите его и на странице Обзор скопируйте значение Идентификатор объекта.

Предостережение

Только соответствующие пользователи должны получать доступ к приложениям, которым предоставлено разрешение DelegatedPermissionGrant.ReadWrite.All .

Шаг 1. Получение делегированных разрешений субъекта-службы ресурса

Сначала найдите делегированные разрешения, предоставляемые субъектом-службой ресурсов. Делегированные разрешения определяются в объекте oauth2PermissionScopes субъекта-службы. В этой статье субъект-служба Microsoft Graph используется в клиенте в качестве субъекта-службы ресурса.

Запрос

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

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq 'Microsoft Graph'&$select=id,displayName,appId,oauth2PermissionScopes

Отклик

Ниже показан пример отклика.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals(id,displayName,appId,oauth2PermissionScopes)",
    "value": [
        {
            "id": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "displayName": "Microsoft Graph",
            "appId": "00000003-0000-0000-c000-000000000000",
            "oauth2PermissionScopes": [
                {
                    "adminConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.",
                    "adminConsentDisplayName": "Read all users' full profiles",
                    "id": "a154be20-db9c-4678-8ab7-66f6cc099a59",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on your behalf.",
                    "userConsentDisplayName": "Read all users' full profiles",
                    "value": "User.Read.All"
                },
                {
                    "adminConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on behalf of the signed-in user.  Also allows the app to read calendar, conversations, files, and other group content for all groups the signed-in user can access. ",
                    "adminConsentDisplayName": "Read all groups",
                    "id": "5f8c59db-677d-491f-a6b8-5f174b11ec1d",
                    "isEnabled": true,
                    "type": "Admin",
                    "userConsentDescription": "Allows the app to list groups, and to read their properties and all group memberships on your behalf.  Also allows the app to read calendar, conversations, files, and other group content for all groups you can access.  ",
                    "userConsentDisplayName": "Read all groups",
                    "value": "Group.Read.All"
                }                
            ]
        }
    ]
}

Шаг 2. Предоставление делегированного разрешения субъекту-службе клиента от имени пользователя

Запрос

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

  • На шаге 1 идентификатор объекта Microsoft Graph в клиенте : 7ea9e944-71ce-443d-811c-71e8047b557a
  • Делегированные User.Read.All разрешения и Group.Read.All идентифицируются по глобально уникальным идентификаторам a154be20-db9c-4678-8ab7-66f6cc099a59 и 5f8c59db-677d-491f-a6b8-5f174b11ec1d соответственно.
  • Субъект — это пользователь, идентифицируемый по идентификатору 3fbd929d-8c56-4462-851e-0eb9a7b3a2a5.
  • Субъект-служба клиента идентифицируется по идентификатору b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94. Это идентификатор объекта субъекта-службы, а не его appId.
POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "scope": "User.Read.All Group.Read.All"
}

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

  • Тип согласия имеет значение AllPrincipals, указывающее, что вы даете согласие от имени всех пользователей в клиенте.
  • Свойство principalId не предоставляется или может иметь значение null.

Ниже приведен пример текста запроса на предоставление согласия от имени всех пользователей:

POST https://graph.microsoft.com/v1.0/oauth2PermissionGrants
Content-Type: application/json

{
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "AllPrincipals",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

Отклик

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants/$entity",
    "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
    "consentType": "Principal",
    "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
    "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
    "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
    "scope": "User.Read.All Group.Read.All"
}

Если вы предоставили согласие всем пользователям в клиенте, параметр consentType в объекте ответа будет иметь значение AllPrincipals, а principalIdnull.

Подтверждение предоставления разрешений

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

Запрос

GET https://graph.microsoft.com/v1.0/oauth2PermissionGrants?$filter=clientId eq 'b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94' and principalId eq '3fbd929d-8c56-4462-851e-0eb9a7b3a2a5' and consentType eq 'Principal'

Отклик

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants",
    "value": [
        {
            "clientId": "b0d9b9e3-0ecf-4bfd-8dab-9273dd055a94",
            "consentType": "Principal",
            "id": "47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl",
            "principalId": "3fbd929d-8c56-4462-851e-0eb9a7b3a2a5",
            "resourceId": "7ea9e944-71ce-443d-811c-71e8047b557a",
            "scope": "User.Read.All Group.Read.All"
        }
    ]
}

Шаг 3. Отмена делегированных разрешений, предоставленных субъекту-службе от имени пользователя [необязательно]

Если субъекту-службе было предоставлено несколько делегированных разрешений от имени пользователя, можно отозвать определенные или все разрешения. Используйте этот метод, чтобы удалить и отозвать согласие для делегированных разрешений, назначенных субъекту-службе клиента.

  • Чтобы отменить одно или несколько разрешений, выполните запрос PATCH для объекта oauth2PermissionGrant и укажите только делегированные разрешения для хранения в параметре область.
  • Чтобы отменить все разрешения, отправьте запрос DELETE объекту oauth2PermissionGrant.

Запрос

Этот запрос отменяет все предоставленные разрешения, User.Read.All кроме разрешения. Он удаляет разрешения и отзывает ранее предоставленное согласие.

PATCH https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl
Content-Type: application/json

{
    "scope": "User.Read.All"
}

Отклик

HTTP/1.1 204 No Content

Запрос

Этот запрос отменяет все предоставленные разрешения для субъекта-службы от имени пользователя.

DELETE https://graph.microsoft.com/v1.0/oauth2PermissionGrants/47nZsM8O_UuNq5Jz3QValETpqX7OcT1EgRxx6AR7VXqdkr0_VoxiRIUeDrmns6Kl

Отклик

HTTP/1.1 204 No Content