アクセス レビュー API を使用してグループへのゲスト アクセスを確認する

  • [アーティクル]

Microsoft Graph のアクセス レビュー API を使用すると、組織は ID (プリンシパルとも呼ばれます) がorganization内のリソースに割り当てられているアクセスを監査して証明できます。 B2B コラボレーションでは、Microsoft 365 グループを使用して、ファイル、メモ、予定表、さらには Teams 会話などのリソースへのゲストのアクセスを効率的に管理できます。 また、アクセス レビュー API を使用することで、組織は、このようなグループへのアクセス権を持つプリンシパルや、organization内の拡張機能など、その他のリソースを定期的に証明できます。

このチュートリアルでは、以下を実行する方法について説明します。

  • ゲストと共に Microsoft 365 グループの定期的なアクセス レビューを作成します。
  • アクセス レビューに適用される決定事項を調査します。

前提条件

このチュートリアルを完了するには、次のリソースと特権が必要です。

  • Microsoft Entra ID P2 またはMicrosoft Entra ID ガバナンス ライセンスが有効になっている、作業Microsoft Entraテナント。
  • テナント内のテスト ゲストとテスト Microsoft 365 グループ。 ゲストは Microsoft 365 グループのメンバーである必要があります。
  • Graph エクスプローラー などの API クライアントにサインインし、少なくとも ID ガバナンス管理者ロールを持つアカウントで Microsoft Graph を呼び出します。
  • 委任されたアクセス許可を自分に付与します。 AccessReview.ReadWrite.All

手順 1: ゲストを含むすべての Microsoft 365 グループのアクセス レビューを作成する

次のアクセス レビュー シリーズでは、次の設定が使用されます。

  • これは定期的なアクセス レビューであり、四半期ごとにレビューされます。
  • グループ所有者は意思決定者です。
  • レビュースコープは、ゲストが含まれる Microsoft 365 グループのみに制限されています。
  • グループに所有者が割り当てられない場合にアクセスを確認できるフォールバック レビュー担当者としてユーザーを定義します。
  • autoApplyDecisionsEnabled が に true設定されています。 この場合、レビュー担当者がアクセス レビューを完了するか、アクセス レビュー期間が終了すると、決定が自動的に適用されます。 有効になっていない場合は、レビューが完了した後、ユーザーが決定を手動で適用する必要があります。
  • applyActions は に removeAccessApplyAction設定されています。 このアクションにより、拒否されたゲストがグループから削除されます。 ゲストは引き続きテナントにサインインできますが、グループのメンバーになることも、グループを通じて付与されるアクセス権も持ちません。

要求

この呼び出しでは、次の値を置き換えます。

  • c9a5aff7-9298-4d71-adab-0a222e0a05e4 フォールバック レビュー担当者の ID を指定します。
  • startDate の値は、今日の日付と endDate の値で、開始日から 1 年の日付です。
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 グループごとに 1 つのインスタンスを返します。

要求

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

応答

この応答では、スコープにはゲストがあるため、テスト グループが含まれます。 この応答では、アクセス レビュー インスタンスは現在 InProgressです。 四半期ごとのレビューであるため、新しいレビュー インスタンスは 3 か月ごとに自動的に作成され、レビュー担当者は新しい決定を適用できます。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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: 意思決定を行う

アクセス レビューのインスタンスに対して行われた決定を取得します。 次のような四半期ごとのレビューで、アクセス レビューがまだアクティブである限り、

  • 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

関連コンテンツ