在 Microsoft Entra ID 中使用 Microsoft Graph API 指派自訂系統管理員角色

發行項
06/22/2024

您可以使用 Microsoft Graph API 將指派角色給使用者帳戶的作業自動化。本文涵蓋 roleAssignments 上的 POST、GET 及 DELETE 作業。

必要條件

Microsoft Entra ID P1 或 P2 授權
特殊權限角色管理員
針對 Microsoft Graph API 使用 Graph 總管時的管理員同意

如需詳細資訊，請參閱使用 PowerShell 或 Graph 總管的必要條件。

RoleAssignment 上的 POST 作業

使用 Create unifiedRoleAssignment API 指派角色。

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

僅會管理單位範圍啟用一部分的內建角色。請參閱此文件，以取得對管理單位所支援的內建角色清單。

RoleAssignment 上的 GET 作業

使用 List unifiedRoleAssignments API 來取得角色指派。

範例 5：取得指定主體的角色指派

GET https://graph.microsoft.com/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://graph.microsoft.com/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：依識別碼取得角色指派

GET https://graph.microsoft.com/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://graph.microsoft.com/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://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

回應

HTTP/1.1 204 No Content

範例 10：刪除不再存在的角色指派

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

回應

HTTP/1.1 404 Not Found

範例 11：刪除自己與全域管理員角色定義之間的角色指派

DELETE https://graph.microsoft.com/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 內建角色
如需預設使用者權限，請參閱預設來賓和成員使用者權限的比較

共用方式為