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

API проверок доступа в Microsoft Graph позволяет организациям выполнять аудит и аттестацию доступа, который удостоверения (также называемые субъектами) назначаются ресурсам в организации. Группы безопасности можно использовать для эффективного управления доступом к ресурсам в организации. Например, доступ к сайту SharePoint, который содержит маркетинговые сборники схем. А с помощью API проверок доступа организации могут периодически заверять субъекты, имеющие доступ к таким группам, и, как расширение, ресурсы в организации.

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

  • Создайте повторяющуюся проверку доступа для членства в группах безопасности.
  • Самостоятельное заверяет необходимость сохранения доступа к группе.

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

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

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

Примечание.

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

Шаг 1. Создание проверки доступа для группы безопасности

Запрос

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

  • eb75ccd2-59ef-48b7-8f76-cc3f33f899f4 с идентификатором группы безопасности.
  • Значение startDate с текущей датой и значение endDate с датой в пять дней от даты начала.

Проверка доступа имеет следующие параметры:

  • Это самоаттестующая проверка, выводимая, если вы не указываете значение для свойства рецензентов . Таким образом, каждый участник группы самостоятельно подтверждает свою потребность в сохранении доступа к группе.
  • Область проверки являются как прямыми, так и транзитивными членами группы.
  • Рецензент должен предоставить обоснование того, почему ей нужно поддерживать доступ к группе.
  • По умолчанию рецензенты Deny не отвечают на запрос на проверку доступа до истечения срока действия экземпляра. Это Deny решение удаляет членов группы из группы.
  • Это одноразовая проверка доступа, которая заканчивается через пять дней. Таким образом, после предоставления доступа пользователю не нужно повторно выполнять самостоятельное аттестацию в течение периода проверки доступа.
  • Субъекты, определенные в область проверки, получают Уведомления по электронной почте и напоминания, которые побуждают их самостоятельно засвидетельствовать необходимость поддержания доступа.
POST https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "One-time self-review for members of Building security",
    "descriptionForAdmins": "One-time self-review for members of Building security",
    "descriptionForReviewers": "One-time self-review for members of Building security",
    "scope": {
        "query": "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "query": "/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
        "queryType": "MicrosoftGraph"
    },
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 5,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2024-03-30"
            }
        }
    }
}

Отклик

Состояние проверки доступа — NotStarted. Вы можете получить проверку доступа (GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b), чтобы отслеживать состояние, и если его состояние — InProgress, то экземпляры были созданы для проверки доступа и принятия решений. Вы также можете получить проверку доступа, чтобы просмотреть ее полные параметры.

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions/$entity",
    "id": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
    "displayName": "One-time self-review for members of Building security",
    "createdDateTime": null,
    "lastModifiedDateTime": null,
    "status": "NotStarted",
    "descriptionForAdmins": "One-time self-review for members of Building security",
    "descriptionForReviewers": "One-time self-review for members of Building security",
    "scope": {},
    "instanceEnumerationScope": {},
    "reviewers": [],
    "fallbackReviewers": [],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Deny",
        "instanceDurationInDays": 5,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recommendationLookBackDuration": null,
        "decisionHistoriesForReviewersEnabled": false,
        "recurrence": {
            "pattern": null,
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2024-03-21",
                "endDate": "2024-03-30"
            }
        },
        "applyActions": [],
        "recommendationInsightSettings": []
    },
    "stageSettings": [],
    "additionalNotificationRecipients": []
}

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

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

Запрос

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances

Отклик

В этом ответе состояние экземпляра связано с тем InProgress , что значение startDateTime прошло, а endDateTime — в будущем. Если параметр startDateTime находится в будущем, состояние равно NotStarted. С другой стороны, если endDateTime находится в прошлом, состояние имеет значение Completed.

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances",
    "value": [
        {
            "id": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "startDateTime": "2024-03-21T17:35:25.24Z",
            "endDateTime": "2024-03-30T08:00:00Z",
            "status": "InProgress",
            "scope": {
                "@odata.type": "#microsoft.graph.accessReviewQueryScope",
                "query": "/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4/transitiveMembers/microsoft.graph.user",
                "queryType": "MicrosoftGraph",
                "queryRoot": null
            },
            "reviewers": [],
            "fallbackReviewers": []
        }
    ]
}

Шаг 3. Проверка связи с пользователем для проверки

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

Запрос

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/contactedReviewers

Отклик

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/contactedReviewers",
    "@odata.count": 2,
    "value": [
        {
            "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "displayName": "Adele Vance",
            "userPrincipalName": "AdeleV@Contoso.com",
            "createdDateTime": "2024-03-21T17:35:34.4092545Z"
        },
        {
            "id": "bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
            "displayName": "Alex Wilber",
            "userPrincipalName": "AlexW@Contoso.com",
            "createdDateTime": "2024-03-21T17:35:34.4092545Z"
        }
    ]
}

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

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

Запрос

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions

Отклик

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#identityGovernance/accessReviews/definitions('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/instances('2d56c364-0695-4ec6-8b92-4c1db7c80f1b')/decisions",
    "@odata.count": 2,
    "value": [
        {
            "id": "4db68765-472d-4aa2-847a-433ea94bcfaf",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "bf59c5ba-5304-4c9b-9192-e5a4cb8444e7",
                "displayName": "Alex Wilber",
                "type": "user",
                "userPrincipalName": "AlexW@Contoso.com",
                "lastUserSignInDateTime": "2/11/2022 5:31:37 PM +00:00"
            }
        },
        {
            "id": "c7de8fba-4d6a-4fab-a659-62ff0c02643d",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
                "displayName": "Adele Vance",
                "type": "user",
                "userPrincipalName": "AdeleV@Contoso.com",
                "lastUserSignInDateTime": "2/11/2022 4:58:13 PM +00:00"
            }
        }
    ]
}

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

Шаг 5. Самостоятельное аттестация на решение о доступе в ожидании

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

Примечание.

Выполните этот шаг в качестве одного из двух членов группы безопасности.

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

Запустите новый сеанс браузера браузера в режиме инкогнито, анонимного или InPrivate и войдите в систему как один из двух участников группы безопасности. Таким образом вы не прерываете текущий сеанс администратора. Кроме того, можно прервать текущий сеанс администратора, выйдя из Graph Обозреватель и выполнив вход в качестве одного из двух участников группы.

Способ 1. Использование API проверок доступа для самостоятельной проверки ожидающего доступа

Вывод списка элементов решений по проверкам доступа

Запрос
GET https://graph.microsoft.com/v1.0/identitygovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions/filterByCurrentUser(on='reviewer')
Отклик

В ответе у вас (Адель Вэнс) есть одна ожидающая проверка доступа (решение ) NotReviewedдля самостоятельной аттестации. Свойства участника и ресурса указывают субъект, к которому применяется решение, и ресурс, доступ к которому находится на рассмотрении. В этом случае Адель Вэнс и группа безопасности соответственно.

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(accessReviewInstanceDecisionItem)",
    "@odata.count": 1,
    "value": [
        {
            "@odata.type": "#microsoft.graph.accessReviewInstanceDecisionItem",
            "id": "c7de8fba-4d6a-4fab-a659-62ff0c02643d",
            "accessReviewId": "2d56c364-0695-4ec6-8b92-4c1db7c80f1b",
            "reviewedDateTime": null,
            "decision": "NotReviewed",
            "justification": "",
            "appliedDateTime": null,
            "applyResult": "New",
            "recommendation": "Approve",
            "principalLink": "https://graph.microsoft.com/v1.0/users/3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
            "resourceLink": "https://graph.microsoft.com/v1.0/groups/eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
            "reviewedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "appliedBy": {
                "id": "00000000-0000-0000-0000-000000000000",
                "displayName": "",
                "type": null,
                "userPrincipalName": ""
            },
            "resource": {
                "id": "eb75ccd2-59ef-48b7-8f76-cc3f33f899f4",
                "displayName": "Building security",
                "type": "group"
            },
            "principal": {
                "@odata.type": "#microsoft.graph.userIdentity",
                "id": "3b8ceebc-49e6-4e0c-9e14-c906374a7ef6",
                "displayName": "Adele Vance",
                "type": "user",
                "userPrincipalName": "AdeleV@Contoso.com",
                "lastUserSignInDateTime": "2/15/2022 9:35:23 AM +00:00"
            }
        }
    ]
}

Запись решения

Чтобы завершить проверку доступа, Адель Вэнс подтверждает необходимость сохранения доступа к группе безопасности.

Запрос возвращает код отклика 204 No Content.

PATCH https://graph.microsoft.com/v1.0/identitygovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/instances/2d56c364-0695-4ec6-8b92-4c1db7c80f1b/decisions/c7de8fba-4d6a-4fab-a659-62ff0c02643d

{
    "decision": "Approve",
    "justification": "As the assistant security manager, I still need access to the building security group."
}

Проверка решений

Чтобы проверить решения, записанные для проверки доступа, выведите список элементов решений по проверке доступа. Хотя период проверки доступа не истек и не применены решения, applyResult помечается как New и вам разрешено изменить решение.

Теперь вы можете выйти из сеанса браузера инкогнито и выйти из него.

Способ 2. Использование портала "Мой доступ"

Кроме того, можно проверка экземпляры проверки доступа на портале "Мой доступ".

  • Список ожидающих проверок доступа. Пользователь может воспользоваться одним из двух способов:

    • Вариант 1. Нажмите кнопку Проверить доступ в уведомлении по электронной почте, полученном в почтовом ящике. Уведомление по электронной почте похоже на следующий снимок экрана. Эта кнопка является прямой ссылкой на ожидающий проверки доступа.

    Email уведомление о проверке доступа.

    • Вариант 2. Перейдите на портал "Мой доступ ". Выберите меню Проверки доступа и перейдите на вкладку Группы и приложения .
  • В списке проверок доступа выберите проверку доступа, для которой вы хотите опубликовать решение. Нажмите кнопку Да , чтобы опубликовать решение о том, что вам по-прежнему нужен доступ к службе безопасности здания. Введите причину, а затем нажмите кнопку Отправить.

    Самостоятельное заверяет необходимость поддержания доступа к ресурсу.

Теперь вы можете выйти из сеанса браузера инкогнито и выйти из него.

Шаг 6. Подтверждение решений и состояния проверки доступа

Вернитесь в сеанс main браузера, где вы по-прежнему вошли с правами администратора, повторите шаг 4, чтобы увидеть, что свойство принятия решений для Adele Vance теперь Approveимеет значение . Когда проверка доступа заканчивается или истечет, решение Deny по умолчанию записывается для Алекса Уилбера. Затем решения применяются автоматически, так как для параметра autoApplyDecisionsEnabled задано значение true и истек период экземпляра проверки доступа. Адель сохраняет доступ к группе безопасности, в то время как Алекс автоматически удаляется из группы.

Поздравляем! Вы создали проверку доступа и самостоятельно заверяли необходимость поддержания доступа. Вы только один раз прошли самостоятельную аттестацию и будете поддерживать доступ до тех пор, пока он не будет удален с Deny помощью решения другого экземпляра проверки доступа или другого внутреннего процесса.

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

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

Запрос возвращает код отклика 204 No Content.

DELETE https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions/2d56c364-0695-4ec6-8b92-4c1db7c80f1b

Заключение

Вы создали проверку доступа, в которой субъекты самостоятельно заверяли необходимость поддержания доступа к ресурсу, в данном случае к группе безопасности "Здание ".

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