Проверка гостевого доступа к группам с помощью API проверки доступа

  • Статья

API проверок доступа в Microsoft Graph позволяет организациям выполнять аудит и аттестацию доступа, который удостоверения (также называемые субъектами) назначаются ресурсам в организации. Благодаря совместной работе B2B вы можете использовать группы Microsoft 365 для эффективного управления доступом гостей к таким ресурсам, как файлы, заметки, календари и даже беседы Teams. С помощью API проверок доступа организации могут периодически заверять субъекты, имеющие доступ к таким группам, а также другие ресурсы в организации.

В этом руководстве рассказывается, как:

  • Создайте повторяющуюся проверку доступа для групп Microsoft 365 с гостями.
  • Изучите решения, которые применяются к проверкам доступа.

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

Для работы с этим руководством вам потребуются следующие ресурсы и привилегии:

  • Рабочий клиент Microsoft Entra с включенной лицензией Microsoft Entra ID P2 или Управление Microsoft Entra ID.
  • Тестовый гость и тестовая группа Microsoft 365 в клиенте. Гость должен быть членом группы Microsoft 365.
  • Войдите в клиент API, например Graph Обозреватель, чтобы вызвать Microsoft Graph с учетной записью, которая имеет по крайней мере роль администратора управления удостоверениями.
  • Предоставьте себе следующие делегированные разрешения: AccessReview.ReadWrite.All.

Шаг 1. Создание проверки доступа для всех групп Microsoft 365 с гостями

В следующей серии проверок доступа используются следующие параметры:

  • Это повторяющаяся проверка доступа и проверка ежеквартально.
  • Владельцы групп являются лицами, принимающими решения.
  • Область проверки ограничен только группами Microsoft 365 с гостями.
  • Он определяет пользователя в качестве резервного рецензента, который может проверить доступ в случае, если группе не назначены владельцы.
  • параметр autoApplyDecisionsEnabled имеет значение true. В этом случае решения применяются автоматически после завершения проверки доступа рецензентом или окончания срока проверки доступа. Если этот параметр не включен, пользователь должен вручную применить решения после завершения проверки.
  • Параметр applyActions имеет значение removeAccessApplyAction. Это действие удаляет запрещенных гостей из группы. Гость по-прежнему может войти в ваш клиент, но не будет входить в группу или не будет иметь прав доступа, предоставляемых через группу.

Запрос

В этом вызове замените следующие значения:

  • c9a5aff7-9298-4d71-adab-0a222e0a05e4 с идентификатором резервного рецензента.
  • Значение startDate с текущей датой и значением endDate с датой на один год от даты начала.
POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Guest access to marketing group",
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/v1.0/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "fallbackReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph"
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 3,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": "P30D",
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "endDate",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2025-03-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ]
    }
}

Отклик

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions/$entity",
    "id": "c22ae540-b89a-4d24-bac0-4ef35e6591ea",
    "displayName": "Guest access to marketing group",
    "createdDateTime": null,
    "lastModifiedDateTime": null,
    "status": "NotStarted",
    "descriptionForAdmins": null,
    "descriptionForReviewers": null,
    "scope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "instanceEnumerationScope": {
        "@odata.type": "#microsoft.graph.accessReviewQueryScope",
        "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph",
        "queryRoot": null
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "fallbackReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 3,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": "P30D",
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "endDate",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2025-03-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ],
        "recommendationInsightSettings": []
    },
    "stageSettings": [],
    "additionalNotificationRecipients": []
}

Шаг 2. Перечисление экземпляров проверки доступа

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

Запрос

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances

Отклик

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

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('c22ae540-b89a-4d24-bac0-4ef35e6591ea')/instances",
    "value": [
        {
            "id": "6392b1a7-9c25-4844-83e5-34e23c88e16a",
            "startDateTime": "2024-03-21T17:00:36.96Z",
            "endDateTime": "2024-03-24T17:00:36.96Z",
            "status": "InProgress",
            "scope": {
                "query": "/groups/59ab642a-2776-4e32-9b68-9ff7a47b7f6a/members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
                "queryType": "MicrosoftGraph"
            }
        }
    ]
}

Шаг 3. Получение решений

Получение решений, принятых для экземпляра проверки доступа. В ежеквартальной проверке, такой как эта, и до тех пор, пока проверка доступа по-прежнему активна:

  • Каждые три месяца создается новый экземпляр проверки.
  • Рецензенты должны применять новые решения для новых экземпляров.

Запрос

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances/6392b1a7-9c25-4844-83e5-34e23c88e16a/decisions

Отклик

В следующем ответе показано решение, принятое для экземпляра проверки.

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('c22ae540-b89a-4d24-bac0-4ef35e6591ea')/instances('6392b1a7-9c25-4844-83e5-34e23c88e16a')/decisions",
    "@odata.count": 1,
    "value": [
        {
            "id": "0e76ee07-b4c6-469e-bc9d-e73fc9a8d660",
            "accessReviewId": "6392b1a7-9c25-4844-83e5-34e23c88e16a",
            "reviewedDateTime": "2021-02-10T17:06:26.147Z",
            "decision": "Approve",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Deny",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "AAD Access Reviews",
                "userPrincipalName": "AAD Access Reviews"
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "userPrincipalName": ""
            },
            "target": {
                "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItemUserTarget",
                "userId": "baf1b0a0-1f9a-4a56-9884-6a30824f8d20",
                "userDisplayName": "John Doe (Tailspin Toys)",
                "userPrincipalName": "john@tailspintoys.com"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "baf1b0a0-1f9a-4a56-9884-6a30824f8d20",
                "displayName": "John Doe (Tailspin Toys)",
                "userPrincipalName": "john@tailspintoys.com"
            }
        }
    ]
}

Шаг 4. Очистка ресурсов

На этом шаге вы удалите определение проверки доступа. Так как определение расписания проверки доступа является схемой проверки доступа, при удалении определения удаляются связанные параметры, экземпляры и решения. Запрос возвращает 204 No Content ответ.

DELETE https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea

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