Konfigurieren des Zugriffsüberprüfungsbereichs mithilfe von Microsoft Graph-APIs

2025-03-18

Mit Microsoft Entra Zugriffsüberprüfungs-APIs können Sie den Zugriff, den Benutzer, Dienstprinzipale oder Gruppen zum Microsoft Entra Von Ressourcen in Ihrem Mandanten haben, programmgesteuert überprüfen.

Konfigurieren Sie die Microsoft Entra Ressourcen, die in der scope-Eigenschaft der accessReviewScheduleDefinition-Ressource überprüft werden sollen. Die folgenden Ressourcen zeigen die Einstellungen zum Konfigurieren des Umfangs der Zugriffsüberprüfung an:

Ressource	Beschreibung	Beispielszenarien für zugriffsüberprüfungen
accessReviewQueryScope	Am besten geeignet, wenn Sie den vollständigen Satz oder die Teilmenge von Prinzipalen überprüfen, die Zugriff auf eine Ressource oder gruppe verwandter Ressourcen haben.	Mitgliedschaft von Benutzern, die einer Gruppe zugewiesen sind, entweder direkte Mitglieder oder direkte und transitive Mitglieder. Gastbenutzerzugriff auf eine Gruppe. Gastbenutzerzugriff auf alle Microsoft 365-Gruppen. Dienstprinzipale, die privilegierten Rollen zugewiesen sind. Benutzer- und Dienstprinzipalzugriff auf Berechtigungsverwaltungs-Zugriffspakete.
accessReviewInactiveUsersQueryScope	Erbt von accessReviewQueryScope. Wird verwendet, wenn nur inaktive Benutzer überprüft werden. Ihr inaktiver status wird durch die inactiveDuration-Eigenschaft angegeben.	Gruppenmitgliedschaft nur für inaktive Benutzer
principalResourceMembershipsScope	Erbt von accessReviewScope. Am besten geeignet, um den Zugriff von Prinzipalen auf Ressourcen zu überprüfen, in denen Sie eindeutige Pools von Prinzipalen und Ressourcen konfigurieren.	Zugriff für drei bestimmte Prinzipale auf eine Microsoft 365-Gruppe und eine privilegierte Microsoft Entra Rolle.

In diesem Artikel wird erläutert, wie Sie ihre Zugriffsüberprüfung durch Konfigurieren der drei abgeleiteten Ressourcentypen festlegen.

Konfigurieren des Bereichs mithilfe von accessReviewQueryScope und accessReviewInactiveUsersQueryScope

Um den Bereich mit dem Ressourcentyp accessReviewQueryScope zu konfigurieren, legen Sie die Werte der Eigenschaften query, queryRoot und queryType fest.

accessReviewInactiveUsersQueryScope erfordert alle Eigenschaften von accessReviewQueryScope und enthält eine inactiveDuration-Eigenschaft .

Beispiele

Hinweis

Die Beispiele in diesem Abschnitt zeigen die einzigen gültigen Kombinationen von principalScopes und resourceScopes, die vom Microsoft Graph-API unterstützt werden.

Beispiel 1: Überprüfen aller Benutzer mit direkter und transitiver Zuweisung zu einer Gruppe

Beispielszenario: Angenommen, Gruppe A hat drei direkte Mitglieder: Benutzer AU1 und AU2 und Gruppe G1. Gruppe G1 hingegen hat zwei Mitglieder : Benutzer GU1 und GU2. Benutzer GU1 und GU2 sind daher transitive Mitglieder der geschachtelten Gruppe G1. Vier Objekte sind in der Überprüfung enthalten: Benutzer AU1, AU2, GU1 und GU2.

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/{groupId}/transitiveMembers",
    "queryType": "MicrosoftGraph"
}

Beispiel 2: Überprüfen aller inaktiven Benutzer mit direkter und transitiver Zuweisung zu einer Gruppe

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "inactiveDuration": "P30D",
    "query": "/groups/{groupId}/transitiveMembers",
    "queryType": "MicrosoftGraph"
}

Beispiel 3: Überprüfen aller Gastbenutzer mit direkter und transitiver Zuweisung zu einer Gruppe

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/groups/{groupId}/transitiveMembers/?$filter=(userType eq 'Guest')",    
    "queryType": "MicrosoftGraph"
}

Beispiel 4: Überprüfen aller Benutzer und Gruppen mit direkter Zuweisung zu einer Gruppe

Im folgenden Beispiel wird die Überprüfung auf direkte Mitglieder der Gruppe ausgerichtet, die entweder Benutzer oder andere Gruppen sind. In diesem Bereich:

Die direkten Benutzer sind in der Überprüfung enthalten.
Die direkten Gruppen sind in der Überprüfung enthalten.
Die transitiven Mitglieder der Gruppen, d. h. Mitglieder geschachtelter Gruppen, werden nicht in die Überprüfung einbezogen.

Beispielszenario: Angenommen, Gruppe A hat drei direkte Mitglieder: Benutzer AU1 und AU2 und Gruppe G1. Gruppe G1 hingegen hat zwei Mitglieder : Benutzer GU1 und GU2. Benutzer GU1 und GU2 sind daher transitive Mitglieder der geschachtelten Gruppe G1. In dieser Überprüfung sind nur drei Objekte vorgesehen: Benutzer AU1 und AU2 und Gruppe G1.

"scope": {
    "query": "/groups/{groupId}/members",
    "queryType": "MicrosoftGraph"
}

Beispiel 5: Überprüfen aller Benutzer mit direkter Zuweisung zu einer beliebigen Microsoft 365-Gruppe

Da diese Überprüfung für alle Microsoft 365-Gruppen gilt, konfigurieren Sie instanceEnumerationScope so, dass die zu überprüfenden Microsoft 365-Gruppen angegeben werden. Gruppen mit dynamischer Mitgliedschaft oder Rollenzuweisung sind in dieser Überprüfung nicht enthalten.

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "./members/microsoft.graph.user",
    "queryType": "MicrosoftGraph"
}

Beispiel 6: Überprüfen aller Gastbenutzer mit direkter Zuweisung zu einer beliebigen Microsoft 365-Gruppe

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph"
}

Beispiel 7: Überprüfen aller inaktiven Gastbenutzer mit direkter Zuweisung zu einer beliebigen Microsoft 365-Gruppe

Da diese Überprüfung für inaktive Benutzer gilt, verwenden Sie die ressource accessReviewInactiveUsersQueryScope , und geben Sie die @odata.type type-Eigenschaft mit dem Wert #microsoft.graph.accessReviewInactiveUsersQueryScopean. Da diese Überprüfung auch für alle Microsoft 365-Gruppen gilt, konfigurieren Sie instanceEnumerationScope so, dass die zu überprüfenden Microsoft 365-Gruppen angegeben werden. Gruppen mit dynamischer Mitgliedschaft oder Rollenzuweisung sind in dieser Überprüfung nicht enthalten.

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified'))",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "inactiveDuration": "P30D"
}

Beispiel 8: Überprüfen aller Gastbenutzer mit direkter Zuweisung zu Teams mit Ausnahme von Teams mit freigegebenen Kanälen

Da diese Überprüfung für alle Teams-zugeordneten Microsoft 365-Gruppen gilt, konfigurieren Sie instanceEnumerationScope so, dass die Teams zugeordneten Microsoft 365-Gruppen angegeben werden, die überprüft werden sollen. Gruppen mit dynamischer Mitgliedschaft oder Rollenzuweisung sind in dieser Überprüfung nicht enthalten.

Diese Überprüfung schließt B2B Direct Connect-Benutzer in Teams mit freigegebenen Kanälen aus. Informationen zum Einschließen von Benutzern mit direkter B2B-Verbindung in Teams mit freigegebenen Kanälen finden Sie unter Beispiel 14: Überprüfen aller Benutzer, die einem Team zugewiesen sind, einschließlich B2B Direct Connect-Benutzern in einem Team mit freigegebenen Kanälen.

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph"
}

Beispiel 9: Überprüfen aller inaktiven Gastbenutzer mit direkter Zuweisung zu Teams

"instanceEnumerationScope": {
    "query": "/groups?$filter=(groupTypes/any(c:c eq 'Unified') and resourceProvisioningOptions/Any(x:x eq 'Team')')",
    "queryType": "MicrosoftGraph"
},
"scope": {
    "@odata.type": "#microsoft.graph.accessReviewInactiveUsersQueryScope",
    "query": "./members/microsoft.graph.user/?$filter=(userType eq 'Guest')",
    "queryType": "MicrosoftGraph",
    "inactiveDuration": "P30D"
}

Beispiel 10: Überprüfen aller Zuweisungen zu Zugriffspaketen für die Berechtigungsverwaltung

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/identityGovernance/entitlementManagement/accessPackageAssignments?$filter=(accessPackageId eq '{package id}' and assignmentPolicyId eq '{id}' and catalogId eq 'id')",
    "queryType": "MicrosoftGraph"
}

Beispiel 11: Überprüfen aller Dienstprinzipale, die einer privilegierten Rolle zugewiesen sind

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleAssignmentScheduleInstances?$expand=principal&$filter=(isof(principal,'microsoft.graph.servicePrincipal') and roleDefinitionId eq '{role ID}')",
    "queryType": "MicrosoftGraph"
}

Beispiel 12: Überprüfen von Benutzern, die einer Microsoft Entra Administratorrolle zugewiesen sind

Beispiel 12.1: Überprüfen aller Benutzer mit aktiven oder berechtigten Zuweisungen zu einer Verzeichnisrolle

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleDefinitions/{role ID}",
    "queryType": "MicrosoftGraph"
}

Beispiel 12.2: Überprüfen aller Benutzer mit berechtigten Zuweisungen zu einer Verzeichnisrolle

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleEligibilityScheduleInstances?$expand=principal&$filter=(isof(principal,'microsoft.graph.user') and roleDefinitionId eq '{role ID}')",
    "queryType": "MicrosoftGraph"
}

Beispiel 12.2: Überprüfen aller Benutzer mit aktiven Zuweisungen zu einer Verzeichnisrolle

"scope": {
    "@odata.type": "#microsoft.graph.accessReviewQueryScope",
    "query": "/roleManagement/directory/roleAssignmentScheduleInstances?$expand=principal&$filter=(assignmentType eq 'Assigned' and isof(principal,'microsoft.graph.user') and roleDefinitionId eq '{role ID}')",
    "queryType": "MicrosoftGraph"
}

Verwenden von principalResourceMembershipsScope zum Konfigurieren des Bereichs

PrincipalResourceMembershipsScope macht die eigenschaften principalScopes und resourceScopes verfügbar, um maßgeschneiderte Konfigurationsoptionen für den Bereich des accessReviewScheduleDefinition-Objekts zu unterstützen. Zu den Funktionen gehört die Überprüfung des Zugriffs für mehrere Prinzipale oder Prinzipalgruppen auf mehrere Ressourcen.

Beispiel 13: Überprüfen aller Benutzer, die einem Team zugewiesen sind, einschließlich B2B Direct Connect-Benutzern in einem Team mit freigegebenen Kanälen

In diesem Beispiel umfasst der Zugriffsüberprüfungsbereich alle Benutzer, die Mitglieder eines Teams sind oder einem freigegebenen Kanal innerhalb des Teams zugewiesen sind. Zu diesen Mitgliedern gehören interne Benutzer, direkte und transitive Benutzer, B2B-Zusammenarbeitsbenutzer und B2B Direct Connect-Benutzer.

"scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/users",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ],
    "resourceScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/groups/{groupId}/transitiveMembers",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        },
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/teams/{groupId}/channels?$filter=(membershipType eq 'shared')",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ]
}

Geben Sie das /teams/{groupId}/channels?$filter=(membershipType eq 'shared')Abfragemuster im resourceScopes-Objekt an, um die direkte B2B-Verbindung mit Benutzern und Teams in freigegebenen Kanälen zu überprüfen. Eine Überprüfung aller Teams , z. B. die Beispiele 8 und 9, enthält keine B2B-Benutzer und -Teams direkt in freigegebenen Kanälen.