Поделиться через

Назначение пользовательских ролей администратора с помощью API Microsoft Graph в идентификаторе Microsoft Entra

  • Статья

Вы можете автоматизировать процесс назначения ролей учетным записям пользователей с помощью API Microsoft Graph. В этой статье рассматриваются операции POST, GET и DELETE назначения ролей.

Необходимые компоненты

  • Лицензия Microsoft Entra ID P1 или P2
  • Администратор привилегированных ролей
  • Согласие администратора при использовании песочницы Graph для Microsoft Graph API.

Дополнительные сведения см. в разделе Предварительные требования для использования PowerShell или песочницы Graph.

Операции POST в назначении ролей

Чтобы назначить роль, используйте API Create unifiedRoleAssignment.

Пример 1. Создание назначения роли для пользователя и определения роли

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

Текст

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  // Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.
}

Отклик

HTTP/1.1 201 Created

Пример 2. Создание назначения роли, для которого не существует субъект или определение роли

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

Текст

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "aaaaaaaa-bbbb-cccc-1111-2222222222229",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  //Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.
}

Отклик

HTTP/1.1 404 Not Found

Пример 3. Создание назначения роли для отдельной области ресурса

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

Текст

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "aaaaaaaa-bbbb-cccc-1111-2222222222229",
    "roleDefinitionId": "00000000-0000-0000-0000-000000000000",    //role template ID of a custom role
    "directoryScopeId": "/13ff0c50-18e7-4071-8b52-a6f08e17c8cc"  //object ID of an application
}

Отклик

HTTP/1.1 201 Created

Пример 4. Создание назначения роли в пределах административной единице для встроенного определения роли, которое не поддерживается

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

Текст

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "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
}

Отклик

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

Для административной единицы разрешено использовать только некоторые встроенные роли. Список встроенных ролей, поддерживаемых в административной области, см. в этом документе.

Операции GET в назначении ролей

Для получения назначения роли используйте API List unifiedRoleAssignments.

Пример 5. Получение назначений ролей для указанного субъекта

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

Response

HTTP/1.1 200 OK
{
"value":[
            { 
                "id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0uIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
                "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
                "directoryScopeId": "/"  
            } ,
            {
                "id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1wIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
                "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "directoryScopeId": "/"
            }
        ]
}

Пример 6. Получение назначений ролей для заданного определения роли

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

Response

HTTP/1.1 200 OK
{
"value":[
            {
                "id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1wIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
                "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "directoryScopeId": "/"
            }
     ]
}

Пример 7. Получение назначения роли по идентификатору

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

Response

HTTP/1.1 200 OK
{ 
    "id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0uIiSDKQoTVJrLE9etXyrY0-1",
    "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
    "directoryScopeId": "/"
}

Пример 8. Получение назначений ролей для указанной области

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

Response

HTTP/1.1 200 OK
{
"value":[
            { 
                "id": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0uIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
                "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
                "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"
            } ,
            {
                "id": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1wIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
                "roleDefinitionId": "00000000-0000-0000-0000-000000000000",
                "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"
            }
        ]
}

Операции DELETE в назначении ролей

Чтобы удалить назначение роли, используйте API Delete unifiedRoleAssignment.

Пример 9. Удаление назначения роли для пользователя и определения роли

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

Response

HTTP/1.1 204 No Content

Пример 10. Удаление назначения роли, которая уже не существует

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

Response

HTTP/1.1 404 Not Found

Пример 11. Удаление назначения роли для самого пользователя и определения роли глобального администратора

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

Response

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

Мы запрещаем пользователям удалять собственные роли глобального администратора, чтобы избежать ситуации, когда в клиенте нет ни одного глобального администратора. Удаление других ролей, назначенных себе, разрешается.

Следующие шаги