次の方法で共有


アクセス レビュー API を使用してセキュリティ グループへのアクセスを確認する

Microsoft Graph のアクセス レビュー API を使用すると、組織は ID (プリンシパルとも呼ばれます) がorganization内のリソースに割り当てられているアクセスを監査して証明できます。 セキュリティ グループを使用して、organization内のリソースへのアクセスを効率的に管理できます。 たとえば、マーケティング プレイブックを含む SharePoint サイトへのアクセスなどです。 また、アクセス レビュー API を使用することで、組織は、このようなグループへのアクセス権を持つプリンシパルと、organization内の拡張機能のリソースを定期的に証明できます。

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

  • セキュリティ グループへのメンバーシップの定期的なアクセス レビューを作成します。
  • グループへのアクセスを維持する必要性を自己証明します。

前提条件

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

  • Microsoft Entra ID P2 またはMicrosoft Entra ID ガバナンス ライセンスが有効になっている、作業Microsoft Entraテナント。
  • テナント内の 2 人のテスト ゲストとテスト セキュリティ グループ。 ゲストはグループのメンバーであり、グループには少なくとも 1 人の所有者が必要です。
  • Graph エクスプローラー などの API クライアントにサインインし、少なくとも ID ガバナンス管理者ロールを持つアカウントで Microsoft Graph を呼び出します。
    • [省略可能]新しい シークレット匿名、または InPrivate ブラウザー ウィンドウを 開きます。 このチュートリアルの後半でサインインします。
  • 委任されたアクセス許可を自分に付与します。 AccessReview.ReadWrite.All

注:

PIM によって管理されるグループのレビューでは、アクティブな所有者のみがレビュー担当者として割り当てられます。 対象となる所有者は含まれません。 PIM によって管理されるグループのアクセス レビューには、少なくとも 1 人のフォールバック レビュー担当者が必要です。 レビューの開始時にアクティブな所有者がいない場合は、フォールバック レビュー担当者にレビューが割り当てられます。

手順 1: セキュリティ グループのアクセス レビューを作成する

要求

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

  • eb75ccd2-59ef-48b7-8f76-cc3f33f899f4 セキュリティ グループの ID を使用します。
  • startDate の値は、今日の日付と endDate の値で、開始日から 5 日の日付です。

アクセス レビューには、次の設定があります。

  • レビュー担当者プロパティの値を指定しない場合に推論される自己証明レビューです。 そのため、各グループ メンバーは、グループへのアクセスを維持する必要性を自己証明します。
  • レビューのスコープは、グループの直接メンバーと推移的メンバーの両方です。
  • レビュー担当者は、グループへのアクセスを維持する必要がある理由の正当な理由を提供する必要があります。
  • 既定の決定は、 Deny レビュー担当者が、インスタンスの有効期限が切れる前にアクセス レビュー要求に応答しない場合です。 この決定により Deny 、グループメンバーがグループから削除されます。
  • 5 日後に終了する 1 回限りのアクセス レビューです。 したがって、アクセスが許可されると、ユーザーはアクセス レビュー期間内にもう一度自己証明する必要はありません。
  • レビューのスコープで定義されているプリンシパルは、アクセスを維持する必要性を自己証明するように求める電子メール通知とリマインダーを受け取ります。
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マークされたら、次のクエリを実行して、アクセス レビュー定義のすべてのインスタンスを一覧表示します。 前の手順で 1 回限りのアクセス レビューを作成したため、要求はスケジュール定義の ID のような ID を持つインスタンスを 1 つだけ返します。

要求

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

応答

この応答では、インスタンスの状態startDateTimeInProgress過去であり、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

応答

次の応答は、セキュリティ グループの 2 人のメンバーに保留中のレビューが通知されたことを示しています。

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

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

応答

次の応答は、レビューのインスタンスに対して行われた決定を示しています。 セキュリティ グループには 2 つのメンバーがあるため、2 つの意思決定項目が必要です。

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

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: 保留中のアクセス決定に対する自己証明

アクセス レビューを自己構成証明として構成しました。 この構成では、グループの両方のメンバーが、グループへのアクセスを維持する必要性を自己証明する必要があります。

注:

この手順は、セキュリティ グループの 2 つのメンバーのいずれかとして実行します。

この手順では、保留中のアクセス レビューを一覧表示し、自己構成証明プロセスを完了します。 この手順は、API を使用するか 、マイ アクセス ポータルを使用して、2 つの方法のいずれかで実行できます。 他の校閲者は自己証明を行わず、代わりに既定の決定がアクセス レビューに適用されます。

新しい シークレット匿名、または InPrivate 閲覧 ブラウザー セッションを開始し、セキュリティ グループの 2 つのメンバーのいずれかとしてサインインします。 これにより、現在の管理者セッションが中断されることはありません。 または、Graph エクスプローラーからログアウトし、2 つのグループ メンバーの 1 つとしてログインし直すことによって、現在の管理者セッションを中断することもできます。

方法 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')
応答

応答から、(Adele Vance) には、自己証明する保留中のアクセス レビュー (決定NotReviewed) が 1 つあります。 プリンシパルリソースのプロパティは、決定が適用されるプリンシパルと、アクセスがレビュー中のリソースを示します。 この場合、Adele Vance とセキュリティ グループはそれぞれです。

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

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"
            }
        }
    ]
}

決定を記録する

アクセス レビューを完了するために、Adele Vance はセキュリティ グループへのアクセスを維持する必要を確認します。

要求は、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: マイ アクセス ポータルを使用する

または、マイ アクセス ポータル ポータルを使用して、保留中のアクセス レビュー インスタンスをチェックすることもできます。

  • 保留中のアクセス レビューを一覧表示します。 ユーザーは、次の 2 つの方法のいずれかに従ってアクセスできます。

    • オプション 1: メールの受信トレイで受信した電子メール通知から [ アクセスの確認 ] ボタンを選択します。 電子メール通知は、次のスクリーンショットのようになります。 このボタンは、保留中のアクセス レビューへの直接リンクです。

    Email通知を使用してアクセス権を確認します。

    • オプション 2: マイ アクセス ポータル ポータルに移動します。 [ アクセス レビュー ] メニューを選択し、[ グループとアプリ ] タブを選択します。
  • アクセス レビューの一覧から、決定を投稿するアクセス レビューを選択します。 [ はい ] を選択して、 セキュリティの構築に引き続きアクセスする必要がある決定を投稿します。 理由を入力し、[送信] を選択 します

    リソースへのアクセスを維持する必要性を自己証明します。

サインアウトしてシークレット ブラウザー セッションを終了できるようになりました。

手順 6: アクセス レビューの決定と状態を確認する

引き続き管理者特権でログインしているメイン ブラウザー セッションに戻り、手順 4 を繰り返して、Adele Vance の decision プロパティが 表示されていることをApprove確認します。 アクセス レビューが終了または期限切れになると、Alex Wilber の既定の Deny 決定が記録されます。 autoApplyDecisionsEnabled が にtrue設定され、アクセス レビュー インスタンスの期間が終了したため、決定が自動的に適用されます。 Adele はセキュリティ グループへのアクセスを維持し、Alex はグループから自動的に削除されます。

おめでとうございます! アクセス レビューを作成し、アクセスを維持する必要性を自己証明しました。 自己証明は 1 回だけであり、別のアクセス レビュー インスタンスの決定または別の内部プロセスによって Deny 削除されるまで、アクセスを維持します。

手順 7: リソースをクリーンアップする

この呼び出しでは、アクセス レビュー定義を削除します。 アクセス レビュー スケジュール定義はアクセス レビューのブループリントであるため、定義を削除すると、関連する設定、インスタンス、決定が削除されます。

要求は、204 No Content 応答コードを返します。

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

まとめ

プリンシパルがリソースへのアクセスを維持する必要性を自己証明するアクセス レビュー (この場合は Building セキュリティ グループ) を作成しました。

このチュートリアルでは、Microsoft Entra アクセス レビュー API のシナリオの 1 つについて説明しました。 アクセス レビュー API は、アクセス構成証明のニーズに合わせてリソース、プリンシパル、レビュー担当者を組み合わせてさまざまなシナリオをサポートします。 詳細については、 アクセス レビュー API に関するページを参照してください。