在 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": "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": "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": "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": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
"principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
"directoryScopeId": "/"
} ,
{
"id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-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": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-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": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-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": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
"principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
"directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"
} ,
{
"id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
"principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
"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 的情況。 允許移除指派給自我的其他角色。
下一步
- 歡迎在 Microsoft Entra 系統管理角色論壇上 與我們分享
- 如需角色許可權的詳細資訊,請參閱 Microsoft Entra 內建角色
- 如需默認用戶權力,請參閱 預設來賓和成員用戶權力的比較
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應