在 Microsoft Entra ID 中使用 Microsoft Graph API 分配自定义管理员角色

项目
07/30/2024

你可以使用 Microsoft Graph API 自动执行将角色分配给用户帐户的过程。本文介绍了 roleAssignment 上的 POST、GET 和 DELETE 操作。

先决条件

Microsoft Entra ID P1 或 P2 许可证
特权角色管理员

RoleAssignment 上的 POST 操作

使用 Create unifiedRoleAssignment API 分配角色。

示例 1：创建用户和角色定义之间的角色分配

POST https://microsoftgraph.chinacloudapi.cn/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://microsoftgraph.chinacloudapi.cn/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://microsoftgraph.chinacloudapi.cn/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://microsoftgraph.chinacloudapi.cn/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."
        }
    }
}

仅为管理单元范围启用了内置角色的子集。请参阅本文档，获取管理单元支持的内置角色的列表。

RoleAssignment 上的 GET 操作

使用 List unifiedRoleAssignments API 获取角色分配。

示例 5：获取给定主体的角色分配

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

响应

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://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId+eq+'<object-id-or-template-id-of-role-definition>'

响应

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

示例 7：按 ID 获取角色分配

GET https://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

响应

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

示例 8：获取给定作用域的角色分配

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

响应

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

RoleAssignment 上的 DELETE 操作

使用 Delete unifiedRoleAssignment API 删除角色分配。

示例 9：删除用户和角色定义之间的角色分配。

DELETE https://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

响应

HTTP/1.1 204 No Content

示例 10：删除不再存在的角色分配

DELETE https://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

响应

HTTP/1.1 404 Not Found

示例 11：删除自身和全局管理员角色定义之间的角色分配

DELETE https://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

响应

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

我们阻止用户删除其自身的全局管理员角色，以避免某个租户的全局管理员数为零的情况出现。允许删除分配给自身的其他角色。

后续步骤

可随时在 Microsoft Entra 管理角色论坛上与我们分享你的观点
有关角色权限的详细信息，请参阅 Microsoft Entra 内置角色
有关默认用户权限，请参阅默认来宾和成员用户权限的比较

通过