Freigeben über

unifiedRoleDefinition: assignedPrincipals

  • Artikel

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Rufen Sie die Liste der Sicherheitsprinzipale (Benutzer, Gruppen und Dienstprinzipale) ab, die einer bestimmten Rolle für verschiedene Bereiche entweder direkt oder transitiv zugewiesen sind. Sie können den $count Abfrageparameter verwenden, um auch die Anzahl abzurufen.

Diese API wird nur für den Verzeichnisanbieter (Microsoft Entra ID) unterstützt.

Verwenden Sie zum Auflisten der direkten und transitiven Rollenzuweisungen für einen bestimmten Prinzipal die API list transitiveRoleAssignments .

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet
✅ ✅ ✅ ✅

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) RoleManagement.Read.Directory Directory.Read.All, RoleManagement.ReadWrite.Directory
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung RoleManagement.Read.Directory Directory.Read.All, RoleManagement.ReadWrite.Directory

Wichtig

In delegierten Szenarien mit Geschäfts-, Schul- oder Unikonten muss dem angemeldeten Benutzer eine unterstützte Microsoft Entra Rolle oder eine benutzerdefinierte Rolle mit einer unterstützten Rollenberechtigung zugewiesen werden. Für diesen Vorgang werden die folgenden Rollen mit den geringsten Berechtigungen unterstützt:

  • Verzeichnisleser
  • Globaler Leser
  • Administrator für privilegierte Rollen

Wichtig

Wenn eine Anwendung eine Beziehung abfragt, die eine directoryObject-Typauflistung zurückgibt, wenn sie nicht über die Berechtigung zum Lesen eines bestimmten Ressourcentyps verfügt, werden Member dieses Typs zurückgegeben, aber mit eingeschränkten Informationen. Beispielsweise wird nur die @odata.type-Eigenschaft für den Objekttyp und die ID zurückgegeben, während andere Eigenschaften als nullangegeben werden. Mit diesem Verhalten können Anwendungen die am wenigsten privilegierten Berechtigungen anfordern, die sie benötigen, anstatt sich auf den Satz von Verzeichnis zu verlassen.*Erlaubnisse. Einzelheiten finden Sie unter Eingeschränkte Informationen, die für nicht zugängliche Mitgliedsobjekte zurückgegeben werden.

HTTP-Anforderung

GET /roleManagement/directory/roleDefinitions/{unifiedRoleDefinitionId}/assignedPrincipals(transitive=@transitive,directoryScopeType='@directoryScopeType',directoryScopeId='@directoryScopeId')

Funktionsparameter

Stellen Sie in der URL der Anforderung die folgenden Abfrageparameter mit Werten bereit. In der folgenden Tabelle sind die Parameter aufgeführt, die mit dieser Funktion verwendet werden können.

Parameter Typ Beschreibung
transitiv Boolesch Gibt an, ob Prinzipale eingeschlossen werden sollen, die über die Gruppenmitgliedschaft (direkt oder transitiv) zugewiesen werden. false standardmäßig.
directoryScopeType String Der Verzeichnisbereich, für den zugewiesene Prinzipale abgerufen werden sollen. Unterstützte Werte sind tenant, administrativeUnitund resource.
directoryScopeId String ID des Verzeichnisbereichs, für den zugewiesene Prinzipale abgerufen werden sollen. Standardmäßig werden alle Bereiche berücksichtigt.

Sie können auch alle unterstützten Funktionsparameter in einer Anforderung kombinieren, um präzise Ergebnisse zu erzielen.

Beispielabfragemuster für directoryScopeType

Bereich Abfrage Unterstützt für
Alle Bereiche /assignedPrincipals(transitive={true | false}) Alle Rollen
Mandantenbereich /assignedPrincipals(directoryScopeType='tenant', transitive={true | false}) Alle Rollen
Alle Verwaltungseinheitsbereiche /assignedPrincipals(directoryScopeType='administrativeUnit', transitive={true | false}) Verzeichnisrollen
Spezifischer Verwaltungseinheitsbereich /assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Verzeichnisrollen
Alle Ressourcenbereiche /assignedPrincipals(directoryScopeType='resource', transitive={true | false}) Verzeichnisrollen
Spezifischer Ressourcenbereich /assignedPrincipals(directoryScopeType='resource', directoryScopeId ='{roleDefinitionId | templateId}', transitive={true | false}) Verzeichnisrollen

Optionale Abfrageparameter

Diese Methode unterstützt die $countOData-Abfrageparameter , $select, $filterund $orderby zum Anpassen der Antwort. Sie können auch mithilfe der OData-Umwandlung nach dem Objekttyp filtern. Beispiel: /assignedPrincipals(transitive=false)/microsoft.graph.user und /assignedPrincipals(transitive=true)/microsoft.graph.servicePrincipal/$count. Allgemeine Informationen finden Sie unter OData-Abfrageparameter.

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
ConsistencyLevel schließlich. Erforderlich. Weitere Informationen zur Verwendung von ConsistencyLevel finden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode an.

Antwort

Wenn die Funktion erfolgreich verläuft, werden der 200 OK Antwortcode und eine directoryObject-Auflistung im Antworttext zurückgegeben.

Beispiele

Betrachten Sie für die Beispiele in diesem Abschnitt das folgende Rollenzuweisungsszenario. Ein Benutzer mit dem Namen User1 verfügt wie folgt über direkte und transitive Rollenzuweisungen:

Benutzer Gruppe Rolle Bereich
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Rolle 1 Bereich1
User1
6c62e70d-f5f5-4b9d-9eea-ed517ed9341f		 Rolle 1 Bereich2
Gruppe1
86b38db7-6e8b-4ad2-b2aa-ced7f09486c1
(User1 ist Mitglied)		 Rolle 1 Bereich1
Gruppe 2
182351a6-d974-4d18-88ae-8a148da44cd2
(User1 ist Mitglied)		 Rolle 1 Bereich1
Gruppe3
b93d5379-a464-4db5-b8e1-694910f1e11e
(User2 ist Mitglied)
(User3 ist Mitglied)		 Rolle 1 Bereich3
  • User1 wird die Rolle "Role1" direkt im Bereich "Scope1" zugewiesen.
  • User1 wird der Rolle "Role1" direkt im Bereich "Scope2" zugewiesen.
  • User1 ist Mitglied der Gruppe1, und Group1 wird die Rolle Role1 im Bereich Scope1 zugewiesen.
  • User1 ist Mitglied der Gruppe 2, und Group2 wird die Rolle Role1 im Bereich Scope1 zugewiesen.
  • User2 ist Mitglied der Gruppe "Group3", und Group3 wird die Rolle "Role1" im Bereich "Scope3" zugewiesen.
  • User3 ist Mitglied der Gruppe 3, und Group3 wird die Rolle Role1 im Bereich Scope3 zugewiesen.

Beispiel 1: Abrufen der Anzahl der direkt und transitiven zugewiesenen Prinzipale für alle Bereiche

Anforderung

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(transitive=true)/$count

Antwort

Die obige Anforderung gibt eine Anzahl von 6 zurück, die die folgenden Rollenzuweisungen darstellt:

  • Zwei direkte Rollenzuweisungen an User1 bei Scope1 und Scope2
  • Zwei transitive Rollenzuweisungen an User1 bis Group1 und Group2
  • Zwei transitive Rollenzuweisungen an Benutzer 2 und Benutzer3 bis Gruppe3.
HTTP/1.1 200 OK
Content-type: text/plain

6

Basierend auf demselben Szenario zeigen die folgenden Beispiele die Anzahl, die für jedes Abfragemuster zurückgegeben wird:

Beispiel Anzahl
/assignedPrincipals(transitive=false)/$count 4
(User1, Group1, Group2, Group3)
/assignedPrincipals(transitive=false)/microsoft.graph.user/$count 1
(Benutzer1)
/assignedPrincipals(transitive=true)/microsoft.graph.user/$count 3
(Benutzer1, Benutzer2, Benutzer3)
/assignedPrincipals(transitive=false)/microsoft.graph.group/$count 3
(Gruppe1, Gruppe2, Gruppe3)
/assignedPrincipals(transitive=true)/microsoft.graph.group/$count 3
(Gruppe1, Gruppe2, Gruppe3)

Beispiel 2: Abrufen direkt zugewiesener Prinzipale für einen bestimmten Verwaltungseinheitsbereich und eine bestimmte Verzeichnisrolle

Anforderung

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='administrativeUnit', directoryScopeId ='d0c2e067-9ae9-4dbf-a280-51a51c46f432')

Antwort

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/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f"
    }
  ]
}

Beispiel 3: Abrufen direkt zugewiesener Prinzipale für alle Bereiche

Anforderung

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals

Antwort

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/beta/$metadata#directoryObjects",
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}

Beispiel 4: Abrufen direkt zugewiesener Benutzer nur für einen mandantenweiten Bereich

Anforderung

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals(directoryScopeType='tenant')/microsoft.graph.user

Antwort

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/beta/$metadata#users",
  "value": [
    {
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    }
  ]
}

Beispiel 5: Abrufen direkt zugewiesener Prinzipale und Inlineanzahl

Im folgenden Beispiel werden die direkt zugewiesenen Prinzipale abgerufen und eine Inlineanzahl angezeigt.

Anforderung

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/644ef478-e28f-4e28-b9dc-3fdde9aa0b1f/assignedPrincipals?$count=true

Antwort

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/beta/$metadata#directoryObjects",
  "@odata.count": 4,
  "value": [
    {
        "@odata.type": "#microsoft.graph.user",
        "id": "6c62e70d-f5f5-4b9d-9eea-ed517ed9341f",
        "displayName": null,
        "userPrincipalName": null
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "86b38db7-6e8b-4ad2-b2aa-ced7f09486c1",
        "displayName": "Group1"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "182351a6-d974-4d18-88ae-8a148da44cd2",
        "displayName": "Group2"
    },
    {
        "@odata.type": "#microsoft.graph.group",
        "id": "b93d5379-a464-4db5-b8e1-694910f1e11e",
        "displayName": "Group3"
    }
  ]
}