Freigeben über

Überprüfen des Gastzugriffs auf Gruppen mithilfe von Zugriffsüberprüfungs-APIs

  • Artikel

Die Zugriffsüberprüfungs-API in Microsoft Graph ermöglicht Es Organisationen, den Zugriff zu überwachen und zu bestätigen, dass Identitäten (auch Prinzipale genannt) Ressourcen im organization zugewiesen werden. Mit der B2B-Zusammenarbeit können Sie Microsoft 365-Gruppen verwenden, um den Zugriff von Gästen auf Ressourcen wie Dateien, Notizen, Kalender und sogar Teams-Unterhaltungen effizient zu verwalten. Durch die Verwendung der Zugriffsüberprüfungs-API können Organisationen in regelmäßigen Abständen Prinzipalen nachweisen, die Zugriff auf solche Gruppen haben, sowie auf andere Ressourcen im organization.

In diesem Tutorial wird Folgendes vermittelt:

  • Erstellen Sie eine wiederkehrende Zugriffsüberprüfung von Microsoft 365-Gruppen mit Gästen.
  • Untersuchen Sie die Entscheidungen, die auf Zugriffsüberprüfungen angewendet werden.

Voraussetzungen

Für dieses Tutorial benötigen Sie die folgenden Ressourcen und Berechtigungen:

  • Ein Funktionierender Microsoft Entra Mandant mit aktivierter Microsoft Entra ID P2- oder Microsoft Entra ID Governance-Lizenz.
  • Einen Testgast und eine Microsoft 365-Testgruppe in Ihrem Mandanten. Der Gast sollte Mitglied der Microsoft 365-Gruppe sein.
  • Melden Sie sich bei einem API-Client wie Graph Explorer an, um Microsoft Graph mit einem Konto aufzurufen, das mindestens über die Rolle Identity Governance-Administrator verfügt.
  • Gewähren Sie sich die folgenden delegierten Berechtigungen: AccessReview.ReadWrite.All.

Schritt 1: Erstellen einer Zugriffsüberprüfung für alle Microsoft 365-Gruppen mit Gästen

Die folgende Zugriffsüberprüfungsreihe verwendet die folgenden Einstellungen:

  • Es handelt sich um eine wiederkehrende Zugriffsüberprüfung, die vierteljährlich überprüft wird.
  • Die Gruppenbesitzer sind die Entscheidungsträger.
  • Der Überprüfungsbereich ist nur auf Microsoft 365-Gruppen mit Gästen beschränkt.
  • Es definiert einen Benutzer als Fallbackprüfer, der den Zugriff überprüfen kann, falls der Gruppe keine Besitzer zugewiesen sind.
  • autoApplyDecisionsEnabled ist auf truefestgelegt. In diesem Fall werden Entscheidungen automatisch angewendet, sobald der Prüfer die Zugriffsüberprüfung abgeschlossen hat oder die Dauer der Zugriffsüberprüfung endet. Wenn diese Option nicht aktiviert ist, muss ein Benutzer die Entscheidungen nach Abschluss der Überprüfung manuell anwenden.
  • applyActions ist auf removeAccessApplyActionfestgelegt. Durch diese Aktion werden abgelehnte Gäste aus der Gruppe entfernt. Der Gast kann sich weiterhin bei Ihrem Mandanten anmelden, ist aber nicht Mitglied der Gruppe oder verfügt nicht über die Zugriffsberechtigungen, die über die Gruppe gewährt werden.

Anforderung

Ersetzen Sie in diesem Aufruf die folgenden Werte:

  • c9a5aff7-9298-4d71-adab-0a222e0a05e4 mit der ID des Fallbackprüfers.
  • Der Wert von startDate mit dem heutigen Datum und dem Wert endDate mit einem Datum, das ein Jahr nach dem Startdatum liegt.
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"
            }
        ]
    }
}

Antwort

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

Schritt 2: Auflisten von Instanzen der Zugriffsüberprüfung

Die folgende Abfrage listet alle Instanzen der Zugriffsüberprüfungsdefinition auf. Wenn in Ihrem Mandanten mehrere Microsoft 365-Gruppen mit Gästen vorhanden sind, gibt diese Anforderung eine instance für jede Microsoft 365-Gruppe mit Gästen zurück.

Anforderung

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

Antwort

In dieser Antwort schließt der Bereich die Testgruppe ein, da er über einen Gast verfügt. In dieser Antwort lautet die zugriffsüberprüfungs-instance derzeit InProgress. Da es sich um eine vierteljährliche Überprüfung handelt, wird automatisch alle drei Monate eine neue Überprüfung instance erstellt, und die Prüfer können neue Entscheidungen anwenden.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

Schritt 3: Abrufen von Entscheidungen

Rufen Sie die Entscheidungen ab, die für die instance einer Zugriffsüberprüfung getroffen werden. In einer vierteljährlichen Überprüfung wie dieser, und solange die Zugriffsüberprüfung noch aktiv ist:

  • Alle drei Monate wird eine neue Überprüfungs-instance erstellt.
  • Prüfer müssen neue Entscheidungen für neue Instanzen anwenden.

Anforderung

GET https://graph.microsoft.com/v1.0/identityGovernance/accessReviews/definitions/c22ae540-b89a-4d24-bac0-4ef35e6591ea/instances/6392b1a7-9c25-4844-83e5-34e23c88e16a/decisions

Antwort

Die folgende Antwort zeigt die Entscheidung, die für die instance der Überprüfung getroffen wurde.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

Schritt 4: Bereinigen von Ressourcen

In diesem Schritt löschen Sie die Zugriffsüberprüfungsdefinition. Da die Definition des Zugriffsüberprüfungszeitplans die Blaupause für die Zugriffsüberprüfung ist, werden beim Löschen der Definition die zugehörigen Einstellungen, Instanzen und Entscheidungen entfernt. Die Anforderung gibt eine 204 No Content Antwort zurück.

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

Verwandte Inhalte