使用访问评审 API 查看对组的来宾访问

  • 项目

Microsoft Graph 中的访问评审 API 使组织能够审核和证明身份 (也称为 主体) 分配给组织中的资源的访问权限。 借助 B2B 协作，你可以使用 Microsoft 365 组有效地管理来宾对文件、笔记、日历甚至 Teams 对话等资源的访问权限。 通过使用访问评审 API，组织可以定期向有权访问此类组的主体以及按扩展证明组织中的其他资源。

在本教程中，你将了解如何：

  • 创建包含来宾的 Microsoft 365 组的定期访问评审。
  • 调查应用于访问评审的决策。

先决条件

若要完成本教程，需要以下资源和特权：

  • 启用了 Microsoft Entra ID P2 或 Microsoft Entra ID 治理 许可证的工作Microsoft Entra租户。
  • 租户中的测试来宾和测试 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 包含回退审阅者的 ID。
  • 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

相关内容