教程:使用访问评审 API 查看对 Microsoft 365 组的来宾访问Tutorial: Use the access reviews API to review guest access to your Microsoft 365 groups

在本教程中,你将使用 Graph 浏览器创建和阅读访问评审,这些评论面向租户中具有来宾用户的所有 Microsoft 365 组。In this tutorial, you will use Graph Explorer to create and read access reviews that targets all Microsoft 365 groups with guest users in the tenant. 若要实现此目的,你将首先使用 Azure AD B2B 邀请并创建租户中的来宾用户(也称为外部标识)。To achieve this, you'll first use Azure AD B2B to invite and create a guest user, also referred to as an external identity, in your tenant. 然后,在创建和阅读访问评审之前,将此来宾用户添加到 Microsoft 365 组中。Then, you'll add this guest user to your Microsoft 365 group prior to creating and reading the access review.

备注

为了可读性,本教程中显示的响应对象可能会缩短。The response objects shown in this tutorial might be shortened for readability.

先决条件Prerequisites

若要完成本教程,需要以下资源和权限:To complete this tutorial, you need the following resources and privileges:

  • 启用 Azure AD Premium P2 或 EMS E5 许可证的工作 Azure AD 租户。A working Azure AD tenant with an Azure AD Premium P2 or EMS E5 license enabled.
  • 不同 Azure AD 租户中的帐户或作为来宾用户邀请的社交标识 (B2B) 。An account in a different Azure AD tenant or a social identity that you can invite as a guest user (B2B user).
  • 以用户 登录 Graph 浏览器 作为用户登录全局管理员角色。Sign in to Graph Explorer as a user in a global administrator role.
  • 以下委派权限 User.Invite.All AccessReview.ReadWrite.All :、、、。 Group.ReadWrite.All User.ReadWrite.AllThe following delegated permissions: User.Invite.All, AccessReview.ReadWrite.All, Group.ReadWrite.All, User.ReadWrite.All.

若要同意 Graph 浏览器中所需的权限:To consent to the required permissions in Graph Explorer:

  1. 选择用户帐户详细信息右侧设置图标,然后选择"选择权限"。Select the settings icon to the right of the user account details, and then choose Select permissions.

    选择 Microsoft Graph 权限 Select the Microsoft Graph permissions

  2. 滚动浏览这些权限的权限列表:Scroll through the list of permissions to these permissions:

    • AccessReviews (3) ,展开,然后选择 AccessReviews.ReadWrite.AllAccessReviews (3), expand and then select AccessReviews.ReadWrite.All.
    • 将 (2) ,展开,然后选择 Group.ReadWrite.All。Group (2), expand and then select Group.ReadWrite.All.
    • 用户 (8) ,展开,然后选择 User.Invite.AllUser.ReadWrite.All。User (8), expand and then select User.Invite.All and User.ReadWrite.All.

    选择“同意”,然后选择“接受”,以接受同意权限。Select Consent, and then select Accept to accept the consent of the permissions. 你不需要代表组织同意这些权限。You do not need to consent on behalf of your organization for these permissions.

    同意 Microsoft Graph 权限 Consent to the Microsoft Graph permissions

步骤 1:在租户中创建测试用户Step 1: Create a test user in your tenant

请求Request

POST /users
Content-Type: application/json

{
    "accountEnabled": true,
    "displayName": "Aline Dupuy",
    "mailNickname": "AlineD",
    "userPrincipalName": "AlineD@contoso.com",
    "passwordProfile": {
        "forceChangePasswordNextSignIn": true,
        "password": "xWwvJ]6NMw+bWH-d"
    }
}

响应Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users/$entity",
    "id": "c9a5aff7-9298-4d71-adab-0a222e0a05e4",
    "displayName": "Aline Dupuy",
    "userPrincipalName": "AlineD@contoso.com",
    "userType": "Member"
}

步骤 2:将来宾用户邀请到租户Step 2: Invite a guest user into your tenant

使用电子邮件地址邀请来宾用户 john@tailspintoys.com 租户。Invite a guest user with the email address john@tailspintoys.com to your tenant.

请求Request

POST https://graph.microsoft.com/beta/invitations
Content-Type: application/json

{
    "invitedUserDisplayName": "John Doe (Tailspin Toys)",
    "invitedUserEmailAddress": "john@tailspintoys.com",
    "sendInvitationMessage": false,
    "inviteRedirectUrl": "https://myapps.microsoft.com"
}

响应Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#invitations/$entity",
    "invitedUser": {
        "id": "baf1b0a0-1f9a-4a56-9884-6a30824f8d20"
    }    
}

步骤 3:创建新的 Microsoft 365 组并添加来宾用户Step 3: Create a new Microsoft 365 group and add the guest user

在此步骤中:In this step:

  1. 创建一个名为 "Feelgood 市场营销活动"的新 Microsoft 365 组。Create a new Microsoft 365 group named Feelgood marketing campaign.
  2. 将自己分配为组所有者。Assign yourself as the group owner.
  3. 添加 john@tailspintoys.com 作为组成员。Add john@tailspintoys.com as a group member. 他们访问组是由你(组所有者)审查的主题。Their access to the group is the subject of review by you, the group owner.

请求Request

在此调用中,替换:In this call, replace:

  • cdb555e3-b33e-4fd5-a427-17fadacbdfa7id 一起。若要检索 id, 请运行 GET https://graph.microsoft.com/beta/mecdb555e3-b33e-4fd5-a427-17fadacbdfa7 with your id. To retrieve your id, run GET on https://graph.microsoft.com/beta/me.
  • baf1b0a0-1f9a-4a56-9884-6a30824f8d20john@tailspintoys.com 步骤 2 中响应 的 id。baf1b0a0-1f9a-4a56-9884-6a30824f8d20 with john@tailspintoys.com's id from the response in Step 2.
POST https://graph.microsoft.com/beta/groups
Content-Type: application/json

{
    "description": "Feelgood Marketing Campaign with external partners and vendors.",
    "displayName": "Feelgood Marketing Campaign",
    "groupTypes": [
        "Unified"
    ],
    "mailEnabled": true,
    "mailNickname": "FeelGoodCampaign",
    "securityEnabled": true,
    "owners@odata.bind": [
        "https://graph.microsoft.com/beta/users/cdb555e3-b33e-4fd5-a427-17fadacbdfa7"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/beta/users/baf1b0a0-1f9a-4a56-9884-6a30824f8d20"
    ]
}

响应Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups/$entity",
    "id": "59ab642a-2776-4e32-9b68-9ff7a47b7f6a",
    "displayName": "Feelgood Marketing Campaign",
    "groupTypes": [
        "Unified"
    ]
}

现在,你有一个具有来宾用户的 Microsoft 365 组。You now have a Microsoft 365 group with a guest user.

步骤 4:为具有来宾用户的所有 Microsoft 365 组创建访问评审Step 4: Create an access review for all Microsoft 365 groups with guest users

为具有来宾用户的所有 Microsoft 365 组创建定期访问评审系列时,计划定期查看来宾对 Microsoft 365 组的访问权限。When you create a recurring access review series for all Microsoft 365 groups with guest users, you schedule a periodic review of the guests' access to the Microsoft 365 group. "Feelgood 市场营销活动"组 进行此操作。Do this for the Feelgood Marketing Campaign group.

访问评审系列使用下列设置:The access review series uses following settings:

  • 这是定期访问评审,每季度查看一次。It's a recurring access review and reviewed quarterly.
  • 组所有者查看来宾用户的持续访问权限。The group owners review the continued access of guest users.
  • 审查范围仅限于具有来宾用户的 Microsoft 365 组。The review scope is limited to Microsoft 365 groups with Guest users only.
  • 备份审阅者。A backup reviewer. 这可以是回退用户或可在组未分配任何所有者的情况下查看访问权限的组。This can be a fallback user or a group that can review the access in case the group doesn't have any owners assigned.
  • autoApplyDecisionsEnabled 设置为 trueautoApplyDecisionsEnabled is set to true. 在这种情况下,一旦审阅者完成访问评审或访问评审持续时间结束,将自动应用决策。In this case, decisions are applied automatically once the reviewer completes the access review or the access review duration ends. 如果未启用,则用户必须在审阅完成后手动应用决策。If not enabled, a user must, after the review completes, apply the decisions manually.
  • removeAccessApplyAction 操作应用于拒绝的来宾用户。Apply removeAccessApplyAction action to denied guest users. 这将删除被拒绝来宾组的成员身份。This removes the membership in the group of the denied guest. 来宾用户仍可登录到你的租户。The guest user can still sign in to your tenant.

请求Request

在此调用中,替换以下内容:In this call, replace the following:

  • c9a5aff7-9298-4d71-adab-0a222e0a05e4 使用 指定为备份审阅者的用户的 ID。c9a5aff7-9298-4d71-adab-0a222e0a05e4 with the id of the user you are designating as a backup reviewer. 这是步骤 1 中响应的 ID。This is the id from the response in Step 1.
  • startDate 的值,其当前日期和 endDate 值,其日期为从开始日期起一年。Value of startDate with today's date and value of endDate with a date one year from the start date.
POST https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions
Content-type: application/json

{
    "displayName": "Group owners review guest across Microsoft 365 groups in the tenant (Quarterly)",
    "descriptionForAdmins": "",
    "descriptionForReviewers": "",
    "scope": {
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph"
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "backupReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "settings": {
        "mailNotificationsEnabled": true,
        "reminderNotificationsEnabled": true,
        "justificationRequiredOnApproval": true,
        "defaultDecisionEnabled": true,
        "defaultDecision": "Approve",
        "instanceDurationInDays": 0,
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2021-02-10",
                "endDate": "2022-12-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ]
    }
}

响应Response

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions/$entity",
    "id": "c22ae540-b89a-4d24-bac0-4ef35e6591ea",
    "displayName": "Group owners review guest across Microsoft 365 groups in the tenant (Quarterly)",
    "status": "NotStarted",
    "createdBy": {
        "id": "cdb555e3-b33e-4fd5-a427-17fadacbdfa7",
        "displayName": "MOD Administrator",
        "userPrincipalName": "admin@contoso.com"
    },
    "scope": {
        "query": "./members/microsoft.graph.user/?$count=true&$filter=(userType eq 'Guest')",
        "queryType": "MicrosoftGraph"
    },
    "instanceEnumerationScope": {
        "query": "/groups?$filter=(groupTypes/any(c:c+eq+'Unified'))&$count=true",
        "queryType": "MicrosoftGraph"
    },
    "reviewers": [
        {
            "query": "./owners",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "backupReviewers": [
        {
            "query": "/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "settings": {
        "defaultDecisionEnabled": true,
        "defaultDecision": "Approve",
        "autoApplyDecisionsEnabled": true,
        "recommendationsEnabled": true,
        "recurrence": {
            "pattern": {
                "type": "absoluteMonthly",
                "interval": 3,
                "month": 0,
                "dayOfMonth": 0,
                "daysOfWeek": [],
                "firstDayOfWeek": "sunday",
                "index": "first"
            },
            "range": {
                "type": "numbered",
                "numberOfOccurrences": 0,
                "recurrenceTimeZone": null,
                "startDate": "2021-02-10",
                "endDate": "2022-12-21"
            }
        },
        "applyActions": [
            {
                "@odata.type": "#microsoft.graph.removeAccessApplyAction"
            }
        ]
    }
}

步骤 5:列出访问评审的实例Step 5: List instances of the access review

以下查询列出了访问评审定义的所有实例。The following query lists all instances of the access review definition. 如果你的测试租户包含具有来宾用户的其他 Microsoft 365 组,此请求将为租户中具有来宾用户的每一个 Microsoft 365 组返回一个实例。If your test tenant contains other Microsoft 365 groups with guest users, this request will return one instance for every Microsoft 365 group with guest users in the tenant.

请求Request

在此调用中, c22ae540-b89a-4d24-bac0-4ef35e6591ea 将 替换为步骤 4 中返回的访问评审定义的 ID。In this call, replace c22ae540-b89a-4d24-bac0-4ef35e6591ea with the id of your access review definition returned in Step 4.

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

响应Response

在此响应中,范围包括一个 id 为 (在步骤 3 中创建的 Feelgood 市场营销活动组) 59ab642a-2776-4e32-9b68-9ff7a47b7f6a 因为它有来宾用户。 In this response, the scope includes a group with id 59ab642a-2776-4e32-9b68-9ff7a47b7f6a (the Feelgood marketing campaign group created in Step 3) because it has a guest user.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#identityGovernance/accessReviews/definitions('c22ae540-b89a-4d24-bac0-4ef35e6591ea')/instances",
    "value": [
        {
            "id": "6392b1a7-9c25-4844-83e5-34e23c88e16a",
            "startDateTime": "2021-02-10T17:00:36.96Z",
            "endDateTime": "2021-02-10T17: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"
            }
        }
    ]
}

在此响应中,访问评审实例当前为 InProgressIn this response, the access review instance is currently InProgress. 因为这是每季度评审一次,每 3 个月将自动创建一个新的审阅实例,并且审阅者可以应用新决策。Because this is a quarterly review, every 3 months, a new review instance is created automatically and you—the reviewer—can apply new decisions.

步骤 6:获取决策Step 6: Get decisions

获取针对访问评审实例做出的决策。Get the decisions taken for the instance of an access review.

请求Request

在此调用中:In this call:

  • c22ae540-b89a-4d24-bac0-4ef35e6591ea 替换为步骤 4 中返回的访问评审定义的 ID。Replace c22ae540-b89a-4d24-bac0-4ef35e6591ea with the id of your access review definition returned in Step 4.
  • 6392b1a7-9c25-4844-83e5-34e23c88e16a 替换为步骤 5 中返回的访问评审实例的 ID。Replace 6392b1a7-9c25-4844-83e5-34e23c88e16a with the id of your access review instance returned in Step 5.
GET https://graph.microsoft.com/beta/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances/6392b1a7-9c25-4844-83e5-34e23c88e16a/decisions

响应Response

以下响应显示为评价实例做出的决定。The following response shows the decision taken for the instance of the review.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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"
            }
        }
    ]
}

因为这是季度评审,并且只要定义仍处于活动状态(即重复的 endDate 不是过去日期,每 3 个月创建一次新的审阅实例,您作为审阅者就可以应用新决策。Because this is a quarterly review and as long as the definition is still active, that is, the recurrence endDate is not a past date, every 3 months when a new review instance is created, you as the reviewer can apply new decisions.

第 7 步:清理资源Step 7: Clean up resources

删除为本教程创建的资源- 体验市场营销活动组、访问 评审 计划定义、来宾用户和测试用户。Delete the resources that you created for this tutorial—Feelgood marketing campaign group, the access review schedule definition, the guest user, and the test user.

删除 Microsoft 365 组Delete the Microsoft 365 group

请求Request

在此调用中, 59ab642a-2776-4e32-9b68-9ff7a47b7f6a 将 替换为 你的 Feelgood 市场营销活动 Microsoft 365 组的 ID。In this call, replace 59ab642a-2776-4e32-9b68-9ff7a47b7f6a with the id of your Feelgood marketing campaign Microsoft 365 group.

DELETE https://graph.microsoft.com/beta/groups/59ab642a-2776-4e32-9b68-9ff7a47b7f6a

响应Response

HTTP/1.1 204 No Content
Content-type: text/plain

删除访问评审定义Delete the access review definition

在此调用中, c22ae540-b89a-4d24-bac0-4ef35e6591ea 将 替换为 访问 评审定义的 ID。In this call, replace c22ae540-b89a-4d24-bac0-4ef35e6591ea with the id of your access review definition. 由于访问评审计划定义是访问评审的蓝图,删除该定义将删除与访问评审相关的设置、实例和决策。Since the access review schedule definition is the blueprint for the access review, deleting the definition will remove the settings, instances, and decisions associated with the access review.

请求Request

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

响应Response

HTTP/1.1 204 No Content
Content-type: text/plain

删除来宾用户Remove the guest user

在此调用中, baf1b0a0-1f9a-4a56-9884-6a30824f8d20 将 替换为 来宾用户的 ID,john@tailspintoys.com。In this call, replace baf1b0a0-1f9a-4a56-9884-6a30824f8d20 with the id of the guest user, john@tailspintoys.com.

请求Request

DELETE https://graph.microsoft.com/beta/users/baf1b0a0-1f9a-4a56-9884-6a30824f8d20

响应Response

HTTP/1.1 204 No Content
Content-type: text/plain

删除测试用户Delete the test user

请求Request

在此调用中, c9a5aff7-9298-4d71-adab-0a222e0a05e4 将 替换为 测试 用户的 ID。In this call, replace c9a5aff7-9298-4d71-adab-0a222e0a05e4 with the id of your test user.

DELETE https://graph.microsoft.com/beta/users/c9a5aff7-9298-4d71-adab-0a222e0a05e4

响应Response

HTTP/1.1 204 No Content
Content-type: text/plain

恭喜!Congratulations! 你已针对租户中 Microsoft 365 组的所有来宾用户创建了访问评审,并计划每季度评估并证明来宾用户的访问权限。You have created an access review for all guest users in Microsoft 365 groups in your tenant, and scheduled quarterly for the evaluation and attestation of the guest users' access. 组所有者将在这些周期内查看访问权限,选择批准或拒绝访问。The group owners will review access during these cycles, choosing either to approve or deny access.

另请参阅See also