使用 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/roleAssignmentScheduleInstances?api-version=2020-10-01&$filter={filter}
   

   GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentSchedules?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/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?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": "P30D" // 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. 將 {roleAssignmentScheduleRequestName} 取代為角色指派的 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/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?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. 將 {roleAssignmentScheduleRequestName} 取代為角色指派的 GUID 識別碼。

啟用合格的角色指派

若要啟用合格角色指派 (取得啟用的存取權) ，請使用 角色指派排程要求 - 建立 REST API 來建立新的要求，並指定安全性主體、角色定義、requestType = SelfActivate 和範圍。 若要呼叫此 API，您必須在範圍上擁有合格的角色指派。

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

2. [選擇性]RoleEligibilitySchedule選擇您想要啟用的 ，並從角色資格排程API 取得 RoleEligibilityScheduleId ，以作為 LinkedRoleEligibilityScheduleId 傳入。 這是選擇性的，如果未傳遞，系統將會挑選 RoleEligibilitySchedule 。

3. 從下列要求著手：

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

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

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. 將 {roleAssignmentScheduleRequestName} 取代為角色指派的 GUID 識別碼。

停用作用中角色指派

若要取消啟用啟動的角色指派 (移除啟用的存取) ，請使用 角色指派排程要求 - 建立 REST API 來建立新的要求，並指定安全性主體、角色定義、requestType = SelfDeactivate 和範圍。 若要呼叫此 API，您必須在範圍上擁有已啟用的角色指派。

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

2. 從下列要求著手：

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

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

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. 將 {roleAssignmentScheduleRequestName} 取代為角色指派的 GUID 識別碼。

Just-Enough-Access (JEA)

如果使用者在資源 (父系) 擁有合格的角色指派，則可以選擇在父資源的子層級範圍啟動角色，而不是整個父範圍。 例如，如果使用者具有 Contributor 訂用帳戶的合格角色，他們可以在訂用帳戶的子資源群組層級啟用角色。

若要取得您具有合格存取權之資源的所有子系列表，您可以使用 合格子資源 API。

1. 從下列要求著手：

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

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

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

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

   篩選	Description
   $filter=resourceType+eq+'Subscription'	列出類型 = 'Subscription' 的資源。
   $filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup''	列出類型 = 'Subscription' 的資源，或類型 = 'ResourceGroup'。

4. id使用任何子資源的 ，作為 scope 啟用的RoleAssignmentScheduleRequest

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

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

錯誤訊息	說明	降低
code：RoleAssignmentExists message：角色指派已經存在。	已存在類似的角色指派	您可以 GET 指派此角色，並確認其排程。
code：RoleAssignmentRequestPolicyValidationFailed message：下列原則規則失敗： [「ExpirationRule」]	要求 ScheduleInfo 中指定的 超過允許的持續時間上限	您可以 GET 為此 RoleDefinitionId 設定RoleManagementPolicy，並檢查RoleManagementPolicyExpirationRule
code：RoleAssignmentRequestPolicyValidationFailed message：下列原則規則失敗： [「JustificationRule」]	您必須在要求本文中指定 Justification	您可以 GET 為此 RoleDefinitionId 設定RoleManagementPolicy，並檢查RoleManagementPolicyEnablementRule
code：RoleAssignmentRequestPolicyValidationFailed message：下列原則規則失敗：[「EligibilityRule」]	啟用此角色的有效 RoleEligibilityScheduleInstance 不存在	資源管理員必須為此主體建立 RoleEligibilityScheduleRequest
code：RoleAssignmentRequestPolicyValidationFailed message：下列原則規則失敗： [「TicketingRule」]	您必須在要求本文中指定 TicketInfo	您可以 GET 為此 RoleDefinitionId 設定RoleManagementPolicy，並檢查RoleManagementPolicyEnablementRule
code：RoleAssignmentRequestPolicyValidationFailed message：下列原則規則失敗：[「MfaRule」]	您需要完成 Azure Multi-Factor Authentication 才能提交此要求	您可以 GET 為此 RoleDefinitionId 設定RoleManagementPolicy，並檢查RoleManagementPolicyEnablementRule