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

  • 文章

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

必要條件

  • Microsoft Entra ID P1 或 P2 授權
  • 特殊權限角色管理員或全域管理員
  • 使用適用于 Microsoft Graph API 的 Graph 總管時管理員同意

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

RoleAssignment 上的 POST 作業

使用建立 unifiedRoleAssignment API 來指派角色。

範例 1：在使用者與角色定義之間建立角色指派

POST https://graph.microsoft.com/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 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": "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.
}

回應

HTTP/1.1 404 Not Found

範例 3：在單一資源範圍上建立角色指派

POST https://graph.microsoft.com/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://graph.microsoft.com/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://graph.microsoft.com/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://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": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "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": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "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": "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://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：刪除自我和全域管理員istrator 角色定義之間的角色指派

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

我們防止使用者刪除自己的全域管理員istrator 角色，以避免租使用者擁有零 Global 管理員istrators 的情況。 允許移除指派給自我的其他角色。

下一步