你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 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}”替换为筛选角色分配列表时要应用的条件。

   筛选器	说明
   $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. 使用角色定义 - List 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并从RoleEligibilityScheduleId角色资格计划 API 获取 作为 传入。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}”替换为筛选角色分配列表时要应用的条件。

   筛选器	说明
   $filter=resourceType+eq+'Subscription'	列出类型 = “Subscription” 的资源。
   $filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup''	列出类型 = “Subscription” 或类型 = “ResourceGroup” 的资源。

4. id使用任何子资源的 用作scope激活的RoleAssignmentScheduleRequest

新请求返回的常见错误

下面列出了创建新请求时可能会遇到的常见错误以及如何缓解这些错误。

错误消息	Explanantion	缓解措施
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 多重身份验证才能提交此请求	可以GET为此RoleDefinitionId使用 RoleManagementPolicy，并检查RoleManagementPolicyEnablementRule