Zuweisen von benutzerdefinierten Administratorrollen mithilfe der Microsoft Graph-API in Microsoft Entra ID

  • Artikel

Mithilfe von Microsoft Graph-API können Sie automatisieren, wie Benutzerkonten Rollen zugewiesen werden sollen. In diesem Artikel werden POST-, GET- und DELETE-Vorgänge für Rollenzuweisungen (roleAssignments) behandelt.

Voraussetzungen

  • P1- oder P2-Lizenz für Microsoft Entra ID
  • „Administrator für privilegierte Rollen“ oder „Globaler Administrator“
  • Administratorzustimmung bei Verwendung von Graph-Tester für die Microsoft Graph-API

Weitere Informationen finden Sie unter Voraussetzungen für die Verwendung von PowerShell oder Graph-Tester.

POST-Vorgänge für RoleAssignment

Verwenden Sie die API Create unifiedRoleAssignment, um die Rolle zuzuweisen.

Beispiel 1: Erstellen einer Rollenzuweisung zwischen einem Benutzer und einer Rollendefinition

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
Content-type: application/json

Body

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  // Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.
}

Antwort

HTTP/1.1 201 Created

Beispiel 2: Erstellen einer Rollenzuweisung, bei der der Prinzipal oder die Rollendefinition nicht vorhanden ist

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

Body

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "2142743c-a5b3-4983-8486-4532ccba12869",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  //Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.
}

Antwort

HTTP/1.1 404 Not Found

Beispiel 3: Erstellen einer Rollenzuweisung für einen einzelnen Ressourcenbereich

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

Body

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "2142743c-a5b3-4983-8486-4532ccba12869",
    "roleDefinitionId": "e9b2b976-1dea-4229-a078-b08abd6c4f84",    //role template ID of a custom role
    "directoryScopeId": "/13ff0c50-18e7-4071-8b52-a6f08e17c8cc"  //object ID of an application
}

Antwort

HTTP/1.1 201 Created

Beispiel 4: Erstellen einer auf den Bereich der Verwaltungseinheit bezogenen Rollenzuweisung für eine integrierte Rollendefinition, die nicht unterstützt wird

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

Body

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId": "29232cdf-9323-42fd-ade2-1d097af3e4de",    //role template ID of Exchange Administrator
    "directoryScopeId": "/administrativeUnits/13ff0c50-18e7-4071-8b52-a6f08e17c8cc"    //object ID of an administrative unit
}

Antwort

HTTP/1.1 400 Bad Request
{
    "odata.error":
    {
        "code":"Request_BadRequest",
        "message":
        {
            "message":"The given built-in role is not supported to be assigned to a single resource scope."
        }
    }
}

Nur eine Teilmenge der integrierten Rollen ist für die Bereichsdefinition der Verwaltungseinheit aktiviert. Eine Liste der integrierten Rollen, die für eine Verwaltungseinheit unterstützt werden, finden Sie in dieser Dokumentation.

GET-Vorgänge für RoleAssignment

Verwenden Sie die API List unifiedRoleAssignments, um die Rollenzuweisung abzurufen.

Beispiel 5: Abrufen von Rollenzuweisungen für einen bestimmten Prinzipal

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=principalId+eq+'<object-id-of-principal>'

Antwort

HTTP/1.1 200 OK
{
"value":[
            { 
                "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
                "directoryScopeId": "/"  
            } ,
            {
                "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "directoryScopeId": "/"
            }
        ]
}

Beispiel 6: Abrufen von Rollenzuweisungen für eine bestimmte Rollendefinition

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId+eq+'<object-id-or-template-id-of-role-definition>'

Antwort

HTTP/1.1 200 OK
{
"value":[
            {
                "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "directoryScopeId": "/"
            }
     ]
}

Beispiel 7: Abrufen einer Rollenzuweisung nach ID

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Antwort

HTTP/1.1 200 OK
{ 
    "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
    "directoryScopeId": "/"
}

Beispiel 8: Abrufen von Rollenzuweisungen für einen bestimmten Bereich

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=directoryScopeId+eq+'/d23998b1-8853-4c87-b95f-be97d6c6b610'

Antwort

HTTP/1.1 200 OK
{
"value":[
            { 
                "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
                "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"
            } ,
            {
                "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "3671d40a-1aac-426c-a0c1-a3821ebd8218",
                "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"
            }
        ]
}

DELETE-Vorgänge für RoleAssignment

Verwenden Sie die API Delete unifiedRoleAssignment, um die Rollenzuweisung zu löschen.

Beispiel 9: Löschen einer Rollenzuweisung zwischen einem Benutzer und einer Rollendefinition

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Antwort

HTTP/1.1 204 No Content

Beispiel 10: Löschen einer Rollenzuweisung, die nicht mehr vorhanden ist

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Antwort

HTTP/1.1 404 Not Found

Beispiel 11: Löschen einer Rollenzuweisung zwischen der eigenen und der Rollendefinition als globaler Administrator

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Antwort

HTTP/1.1 400 Bad Request
{
    "odata.error":
    {
        "code":"Request_BadRequest",
        "message":
        {
            "lang":"en",
            "value":"Removing self from Global Administrator built-in role is not allowed"},
            "values":null
        }
    }
}

Es wird verhindert, dass Benutzer die eigene Rolle als globaler Administrator löschen, um ein Szenario zu vermeiden, in dem ein Mandant keine globalen Administratoren aufweist. Das Entfernen anderer zugewiesenen Rollen ist zulässig.

Nächste Schritte