使用 Azure PIM 以 REST API 管理合格存取

Azure Privileged Identity Management (PIM) 可讓您限制特殊許可權角色的常設系統管理員存取權、探索誰具有存取權，以及檢閱特殊許可權存取權。 本文說明使用 REST API 管理存取的常見方式。

列出合格的指派

若要列出合格角色指派 (清單存取) ，您可以使用其中一個 角色資格排程實例 - 範圍 或 角色資格排程清單 - 範圍 REST API 的清單。 若要精簡您的結果，請指定範圍和選擇性篩選條件。 若要呼叫此 API，您必須有權存取指定範圍內的 Microsoft.Authorization/roleAssignments/read 作業。 所有 內建角色 都會獲得此作業的存取權。

1. 從下列要求著手：

   GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleInstances?api-version=2020-10-01&$filter={filter}
   

   GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilitySchedules?api-version=2020-10-01&$filter={filter}
   

2. 在 URI 中，將 {scope} 取代為要列出角色指派的範圍。

   範圍	類型
   providers/Microsoft.Management/managementGroups/{mg-name}	管理群組
   subscriptions/{subscriptionId}	訂用帳戶
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	資源群組
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1	資源

3. 將 {filter} 取代為您要針對角色指派清單篩選套用的條件。

   篩選	Description
   $filter=atScope()	僅列出指定範圍的角色指派，不包括子範圍內的角色指派。
   $filter=principalId%20eq%20'{objectId}'	列出所指定使用者、群組或服務主體的角色指派。
   $filter=roleDefinitionId%20eq%20'{roleDefinitionId}'	列出指定角色定義的角色指派。
   $filter=assignedTo('{objectId}')	列出所指定使用者的角色指派，包括從群組繼承的角色指派。
   $filter=asTarget()	列出目前使用者或服務主體的角色指派，包括繼承自群組的角色指派。
   $filter=assignedTo('{objectId}')+and+atScope()	列出指定使用者的角色指派，包括只繼承自指定範圍之群組的角色指派，不包括子範圍的角色指派。

授與合格指派

若要建立合格的角色指派 (授與存取權) ，請使用 角色資格排程要求 - 建立 REST API 並指定安全性主體、角色定義、排程、requestType = AdminAssign 和範圍。 若要呼叫此 API，您必須能夠存取 Microsoft.Authorization/roleAssignments/write 作業。 在內建角色中，只有擁有者和使用者存取系統管理員會獲得這項作業的存取權。

1. 使用角色定義 - 列出 REST API 或參閱內建角色，以取得您要指派角色定義的識別碼。

2. 使用 GUID 工具來產生將用於角色指派識別碼的唯一識別碼。 此識別碼的格式：00000000-0000-0000-0000-000000000000

3. 從下列要求和本文著手：

   PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleRequests/{roleEligibilityScheduleRequestName}?api-version=2020-10-01
   

   {
     "Properties": {
       "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
       "PrincipalId": "{principalId}",
       "RequestType": "AdminAssign",
       "ScheduleInfo": {
         "StartDateTime": "2020-09-09T21:31:27.91Z",
         "Expiration": {
           "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
           "EndDateTime": null,
           "Duration": "P365D" // Use ISO 8601 format
         }
       }
     }
   }
   

4. 在 URI 中，將 {scope} 取代為角色指派的範圍。

   範圍	類型
   providers/Microsoft.Management/managementGroups/{mg-name}	管理群組
   subscriptions/{subscriptionId}	訂用帳戶
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	資源群組
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1	資源

5. 將 {roleEligibilityScheduleRequestName} 取代為角色指派的 GUID 識別碼。

6. 在要求本文中，將 {subscriptionId} 取代為您的訂用帳戶識別碼。

7. 將 {roleDefinitionId} 取代為角色定義識別碼。

8. 將 {principalId} 取代為使用者、群組或服務主體 (將獲得角色指派) 的物件識別碼。

移除合格指派

若要移除合格角色指派 (移除存取權) ，請使用 角色資格排程要求 - 建立 REST API 來建立新的要求來撤銷指派，並指定安全性主體、角色定義、requestType = AdminRemove 和範圍。 若要呼叫這個 API，您必須具有 Microsoft.Authorization/roleAssignments/write 作業的存取權。 在內建角色中，只有擁有者和使用者存取系統管理員會獲得這項作業的存取權。

1. 使用 GUID 工具來產生將用於角色指派識別碼的唯一識別碼。 此識別碼的格式：00000000-0000-0000-0000-000000000000

2. 從下列要求著手：

   PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleRequests/{roleEligibilityScheduleRequestName}?api-version=2020-10-01
   

   {
     "Properties": {
       "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
       "PrincipalId": "{principalId}",
       "RequestType": "AdminRemove"
       }
   }
   

3. 在 URI 中，將 {scope} 取代為要移除角色指派的範圍。

   範圍	類型
   providers/Microsoft.Management/managementGroups/{mg-name}	管理群組
   subscriptions/{subscriptionId}	訂用帳戶
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	資源群組
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1	資源

4. 將 {roleEligibilityScheduleRequestName} 取代為角色指派的 GUID 識別碼。

針對新要求傳回的常見錯誤

以下是您在建立新要求時可能會遇到的常見錯誤清單，以及如何減輕這些錯誤。