在 Azure Active Directory 中使用 Microsoft 图形 API 分配自定义管理员角色Assign custom admin roles using the Microsoft Graph API in Azure Active Directory

你可以使用 Microsoft Graph API 自动执行将角色分配给用户帐户的过程。You can automate how you assign roles to user accounts using the Microsoft Graph API. 本文介绍了 roleAssignment 上的 POST、GET 和 DELETE 操作。This article covers POST, GET, and DELETE operations on roleAssignments.

所需的权限Required permissions

使用全局管理员或特权角色管理员帐户连接到 Azure AD 组织,以分配或删除角色。Connect to your Azure AD organization using a Global administrator or Privileged role administrator account to assign or remove roles.

RoleAssignment 上的 POST 操作POST Operations on RoleAssignment

示例 1:创建用户和角色定义之间的角色分配。Example 1: Create a role assignment between a user and a role definition.

POSTPOST

POST https://microsoftgraph.chinacloudapi.cn/beta/roleManagement/directory/roleAssignments
Content-type: application/json

BodyBody

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

响应Response

HTTP/1.1 201 Created

示例 2:创建在其中不存在主体或角色定义的角色分配Example 2: Create a role assignment where the principal or role definition does not exist

POSTPOST

https://microsoftgraph.chinacloudapi.cn/beta/roleManagement/directory/roleAssignments

BodyBody

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

响应Response

HTTP/1.1 404 Not Found

示例 3:在单个资源范围上创建角色分配Example 3: Create a role assignment on a single resource scope

POSTPOST

https://microsoftgraph.chinacloudapi.cn/beta/roleManagement/directory/roleAssignments

正文Body

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

响应Response

HTTP/1.1 201 Created

示例 4:在不受支持的内置角色定义上创建管理单元范围角色分配Example 4: Create an administrative unit scoped role assignment on a built-in role definition which is not supported

POSTPOST

https://microsoftgraph.chinacloudapi.cn/beta/roleManagement/directory/roleAssignments

正文Body

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

响应Response

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

仅为管理单元范围启用了内置角色的子集。Only a subset of built-in roles are enabled for Administrative Unit scoping. 请参阅本文档,获取管理单元支持的内置角色的列表。Refer to this documentation for the list of built-in roles supported over an administrative unit.

RoleAssignment 上的 GET 操作GET Operations on RoleAssignment

示例 5:获取给定主体的角色分配Example 5: Get role assignments for a given principal

GETGET

https://microsoftgraph.chinacloudapi.cn/beta/roleManagement/directory/roleAssignments&$filter=principalId eq ‘<object-id-of-principal>’

响应Response

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:获取给定角色定义的角色分配。Example 6: Get role assignments for a given role definition.

GETGET

https://microsoftgraph.chinacloudapi.cn/beta/roleManagement/directory/roleAssignments&$filter=roleDefinitionId eq ‘<object-id-or-template-id-of-role-definition>’

响应Response

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

示例 7:按 ID 获取角色分配。Example 7: Get a role assignment by ID.

GETGET

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

响应Response

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

示例 8:获取给定作用域的角色分配Example 8: Get role assignments for a given scope

GETGET

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

响应Response

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 Operations on RoleAssignment

示例 9:删除用户和角色定义之间的角色分配。Example 9: Delete a role assignment between a user and a role definition.

DELETEDELETE

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

响应Response

HTTP/1.1 204 No Content

示例 10:删除不再存在的角色分配Example 10: Delete a role assignment that no longer exists

DELETEDELETE

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

响应Response

HTTP/1.1 404 Not Found

示例 11:删除自身和全局管理员角色定义之间的角色分配Example 11: Delete a role assignment between self and Global Administrator role definition

DELETEDELETE

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

我们阻止用户删除其自身的全局管理员角色,以避免某个租户的全局管理员数为零的情况出现。We prevent users from deleting their own Global Administrator role to avoid a scenario where a tenant has zero Global Administrators. 允许删除分配给自身的其他角色。Removing other roles assigned to self is allowed.

后续步骤Next steps