Freigeben über

Konfigurieren des Umfangs von Zugriffsüberprüfungen mithilfe von Zugriffsüberprüfungs-APIs

  • Artikel

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

Sie konfigurieren die Microsoft Entra Ressourcen, die in der scope-Eigenschaft der ressource accessReviewScheduleDefinition überprüft werden sollen. Die folgenden Ressourcen machen die Einstellungen verfügbar, um den Umfang der Zugriffsüberprüfung zu konfigurieren:

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 erfahren Sie, wie Sie ihre Zugriffsüberprüfung durch Konfigurieren der drei abgeleiteten Ressourcentypen festlegen.

      Konfigurieren des Bereichs mithilfe von accessReviewQueryScope und accessReviewInactiveUsersQueryScope

      Um den Bereich mithilfe des accessReviewQueryScope-Ressourcentyps 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

      Da diese Überprüfung auf inaktive Benutzer angewendet wird, verwenden Sie die ressource accessReviewInactiveUsersQueryScope , und geben Sie die typeigenschaft @odata.type mit dem Wert #microsoft.graph.accessReviewInactiveUsersQueryScopean.

      "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 nur auf direkte Mitglieder der Gruppe definiert, 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 auf alle Microsoft 365-Gruppen angewendet wird, konfigurieren Sie instanceEnumerationScope so, dass die zu überprüfenden Microsoft 365-Gruppen angegeben werden. Gruppen, die eine dynamische Mitgliedschaft aufweisen oder Rollen zugewiesen werden können, 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

      Da diese Überprüfung auf alle Microsoft 365-Gruppen angewendet wird, konfigurieren Sie instanceEnumerationScope so, dass die zu überprüfenden Microsoft 365-Gruppen angegeben werden. Gruppen, die eine dynamische Mitgliedschaft aufweisen oder Rollen zugewiesen werden können, 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/?$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 auf inaktive Benutzer angewendet wird, verwenden Sie die ressource accessReviewInactiveUsersQueryScope , und geben Sie die typeigenschaft @odata.type mit dem Wert #microsoft.graph.accessReviewInactiveUsersQueryScopean. Da diese Überprüfung auf alle Microsoft 365-Gruppen angewendet wird, konfigurieren Sie instanceEnumerationScope so, dass die zu überprüfenden Microsoft 365-Gruppen angegeben werden. Gruppen, die eine dynamische Mitgliedschaft aufweisen oder Rollen zugewiesen werden können, 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 auf alle Teams-zugeordneten Microsoft 365-Gruppen angewendet wird, konfigurieren Sie instanceEnumerationScope so, dass die Teams zugeordneten Microsoft 365-Gruppen angegeben werden, die überprüft werden sollen. Gruppen, die eine dynamische Mitgliedschaft aufweisen oder Rollen zugewiesen werden können, sind in dieser Überprüfung nicht enthalten.

      Diese Überprüfung umfasst keine direkten B2B-Verbindungsbenutzer in Teams mit freigegebenen Kanälen. 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

      Da diese Überprüfung auf alle Teams-zugeordneten Microsoft 365-Gruppen angewendet wird, konfigurieren Sie instanceEnumerationScope so, dass die Teams zugeordneten Microsoft 365-Gruppen angegeben werden, die überprüft werden sollen. Gruppen, die eine dynamische Mitgliedschaft aufweisen oder Rollen zugewiesen werden können, sind in dieser Überprüfung nicht enthalten.

      Diese Überprüfung umfasst keine direkten B2B-Verbindungsbenutzer in Teams mit freigegebenen Kanälen. 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.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 besteht der Zugriffsüberprüfungsbereich aus allen Benutzern, 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
        }
    ]
}

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

      Hinweis

      Die Zugriffsüberprüfung von Benutzern und Teams mit direkter B2B-Verbindung wird nur für einstufige Zugriffsüberprüfungen und nicht für mehrstufige Zugriffsüberprüfungen unterstützt.

      Beispiel 14: Überprüfen aller Gastbenutzer, die einer Verzeichnisrolle zugewiesen sind

      "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/users?$filter=(userType eq 'Guest')",
            "queryType": "MicrosoftGraph"
        }
    ],
    "resourceScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/roleManagement/directory/roleDefinitions/{role id}",
            "queryType": "MicrosoftGraph"
        }
    ]
}

      Beispiel 15: Überprüfen aller Benutzer mit direkter oder transitiver Zuweisung zu einer Anwendung

      "scope": {
    "@odata.type": "#microsoft.graph.principalResourceMembershipsScope",
    "principalScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/v1.0/users",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        },
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "./members/microsoft.graph.user",
            "queryType": "MicrosoftGraph",
            "queryRoot": "/v1.0/groups"
        }
    ],
    "resourceScopes": [
        {
            "@odata.type": "#microsoft.graph.accessReviewQueryScope",
            "query": "/v1.0/servicePrincipals/{servicePrincipalId}",
            "queryType": "MicrosoftGraph",
            "queryRoot": null
        }
    ]
}

      Verwandte Inhalte