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

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

先决条件

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

有关详细信息,请参阅使用 PowerShell 的先决条件

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": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  // Don't use "resourceScope" attribute in Microsoft Entra 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": "2142743c-a5b3-4983-8486-4532ccba12869",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  //Don't use "resourceScope" attribute in Microsoft Entra 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": "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
}

响应

HTTP/1.1 201 Created

示例 4:在不受支持的内置角色定义上创建管理单元范围角色分配

POST https://microsoftgraph.chinacloudapi.cn/v1.0/roleManagement/directory/roleAssignments

正文

{
    "@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
}

响应

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

示例 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": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "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": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "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": "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"
            }
        ]
}

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

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

后续步骤