为 Privileged Identity Management 的角色激活配置自定义扩展（预览版）

Microsoft Entra Privileged Identity Management（PIM）中的自定义扩展使组织能够将自定义业务逻辑集成到角色激活过程中。这些扩展作为 PIM 在策略评估期间调用的 REST API 实现。自定义扩展会评估激活请求，并向 PIM 返回一个决定，指示是应允许还是拒绝激活。

使用自定义扩展可以：

针对内部系统验证票证编号。
强制实施基于 HR 的访问规则，例如就业状态或角色资格。
集成合规性工作流或审核系统。
基于业务上下文应用动态审批逻辑。

自定义扩展支持组的 PIM、Microsoft Entra 角色的 PIM 和 Azure 资源的 PIM。

Important

PIM 的自定义扩展处于预览状态。有关适用于 beta 版、预览版或尚未正式发布的 Azure 功能的法律条款，请参阅 Azure 预览补充使用条款。

许可证要求

将自定义扩展与 PIM 结合使用需要有效的 Microsoft Entra ID 治理（EIG）或 Entra 套件许可证。有关许可的详细信息，请参阅：Microsoft Entra ID 治理许可基础知识。

先决条件

至少分配 特权角色管理员 角色。
接受 HTTP POST 请求并返回 PIM 预期格式的评估响应的 REST API 终结点。该 API 可以采用任何语言生成，并托管在任何平台上。
Microsoft Entra ID应用程序注册，以保护 PIM 与自定义扩展终结点之间的通信。
Microsoft 图形 API beta 终结点是必需的，因为此功能处于预览状态。
以下 Microsoft Graph 委托权限，具体取决于所执行的操作：

操作权限（最低特权）

创建或更新自定义扩展 PrivilegedAccess-CustomExt.ReadWrite.All

获取或列出自定义扩展 PrivilegedAccess-CustomExt.Read.All

操作	权限（最低特权）
创建或更新自定义扩展	`PrivilegedAccess-CustomExt.ReadWrite.All`
获取或列出自定义扩展	`PrivilegedAccess-CustomExt.Read.All`

生成自定义扩展终结点

生成接受来自 PIM 的 HTTP POST 请求的 REST API。在角色激活期间，PIM 会向你的终结点发送请求负载，其中包含对此次激活进行评估所需的信息。 API 评估请求并返回一个响应，指示是应批准、自动批准还是拒绝激活。

PIM 发送的请求模型取决于资源类型：Microsoft Entra 组、Microsoft Entra 角色或 Azure 资源。以下部分提供了基于正在使用的资源类型的示例。

适用于组的 PIM 请求模型

在 PIM 组的请求模型中，PIM 发送对象 privilegedAccessGroupAssignmentScheduleRequest 。有关完整架构，请参阅 Create assignmentScheduleRequest。

{
  "@odata.type": "#microsoft.graph.privilegedAccessGroupAssignmentScheduleRequest",
  "id": "String (identifier)",
  "status": "String",
  "action": "String",
  "justification": "String",
  "principalId": "String",
  "accessId": "String",
  "groupId": "String",
  "scheduleInfo": {
    "@odata.type": "microsoft.graph.requestSchedule"
  },
  "ticketInfo": {
    "@odata.type": "microsoft.graph.ticketInfo"
  }
}

用于 Microsoft Entra 角色的 PIM 请求模型

在 PIM Microsoft Entra 角色的请求模型中，PIM 发送unifiedRoleAssignmentScheduleRequest 对象。有关完整架构，请参阅 Create roleAssignmentScheduleRequests。

{
  "@odata.type": "#microsoft.graph.unifiedRoleAssignmentScheduleRequest",
  "id": "String (identifier)",
  "status": "String",
  "action": "String",
  "principalId": "String",
  "roleDefinitionId": "String",
  "directoryScopeId": "String",
  "justification": "String",
  "scheduleInfo": {
    "@odata.type": "microsoft.graph.requestSchedule"
  },
  "ticketInfo": {
    "@odata.type": "microsoft.graph.ticketInfo"
  }
}

针对 Azure 资源的 PIM 请求模型

在针对 Azure 资源的 PIM 请求模型中，PIM 会发送角色分配计划请求对象。有关完整架构，请参阅角色分配计划请求 - 创建。

{
  "properties": {
    "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
    "principalType": "User",
    "requestType": "SelfActivate",
    "roleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "scope": "/subscriptions/{subscriptionId}",
    "justification": "String",
    "scheduleInfo": {
      "startDateTime": "2020-09-09T21:35:27.91Z",
      "expiration": {
        "type": "AfterDuration",
        "duration": "PT8H"
      }
    },
    "ticketInfo": {
      "ticketNumber": "String",
      "ticketSystem": "String"
    }
  }
}

响应模型

自定义扩展评估激活请求后，它必须返回对 PIM 的响应，其中包括评估结果和支持的详细信息。

领域	类型	Description
`evaluationId`	String	由自定义扩展为该评估生成的唯一标识符。此值会记入 PIM 审计记录中，以便追溯。
`evaluationOutcome`	String	评估的结果。支持的值：`Approved`、`AutoApproved`、`Denied`。
`reason`	列出<字符串>	解释评估结果的消息。当请求被拒绝时，这些消息会显示在 UI 中。

以下示例展示了每种结果对应的有效响应负载：

已批准：所有验证检查均已通过，激活将按正常的 PIM 工作流进行：

{
  "evaluationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
  "evaluationOutcome": "Approved",
  "reason": ["Valid request"]
}

AutoApproved：请求满足自动审批的条件，激活将继续，无需手动 PIM 审批：

{
  "evaluationId": "bbbb1111-cc22-3333-44dd-555555eeeeee",
  "evaluationOutcome": "AutoApproved",
  "reason": ["High severity incident for on-call engineer, bypass manual approval"]
}

被拒绝：一个或多个验证检查失败，PIM 阻止激活：

{
  "evaluationId": "cccc2222-dd33-4444-55ee-666666ffffff",
  "evaluationOutcome": "Denied",
  "reason": ["Requestor has not cleared Cloud Screening"]
}

保护自定义扩展服务

通过注册Microsoft Entra ID应用程序和配置令牌验证来保护 PIM 与自定义扩展 REST API 之间的通信。

注册Microsoft Entra ID应用程序

自定义扩展服务必须由Microsoft Entra ID应用程序提供支持。 PIM 使用此应用注册向自定义扩展终结点进行身份验证，并请求 API 的访问令牌。若要注册Microsoft Entra ID应用程序，请执行以下步骤：

请以至少应用程序开发人员的身份登录到Microsoft Entra 管理中心。
转到 Identity>Applications>应用注册。
选择新建注册。
输入描述性应用程序名称，例如 Contoso PIM Custom Extension API。
对于“支持的帐户类型”设置，请选择“仅限此组织目录中的帐户”。
此类服务间注册无需重定向 URI。
选择注册。

配置应用程序 ID URI

创建应用后，配置应用程序 ID URI。应用程序 ID URI 中的主机名必须与自定义扩展终结点 URL 的主机名匹配。

打开应用注册并转到 “公开 API”。
选择设置（位于应用程序 ID URI旁边）。
输入表示 API 的值。 URI 必须以应用注册的应用程序（客户端）ID 结尾。例如，如果自定义扩展终结点为 https://api.contoso.com/webhooks/entra-role-assignments，且应用程序（客户端）ID 为 00001111-aaaa-2222-bbbb-3333cccc4444，请将应用程序 ID URI 设置为：api://api.contoso.com/00001111-aaaa-2222-bbbb-3333cccc4444
选择“保存”。

保存应用程序 ID URI。在 PIM 中配置自定义扩展时，提供此值 resourceId 。

验证 API 中的持有者令牌

当 PIM 调用自定义扩展 REST API 时，它会发送 HTTP 授权标头，其中包含由Microsoft Entra ID颁发的持有者令牌。在 API 中实现以下令牌验证检查：

调用应用程序声明 - 验证 appid 声明（对于 V1 令牌）或 azp 声明（对于 V2 令牌）是否包含值 1c67c054-65c8-4f7f-92a1-eb7ba6e48627。此值将Microsoft Entra Privileged Identity Management标识为调用方。
受众声明 - 验证 aud 声明是否包含你为应用注册配置的应用程序 ID URI。
颁发者声明 - 验证 iss 声明是否包含适用于你的租户的 Microsoft Entra 颁发者 URL：https://login.partner.microsoftonline.cn/{tenantId}/v2.0。

将自定义扩展载入 PIM

在租户内创建自定义扩展，以便 PIM 可以在角色激活请求期间调用你的终结点。创建扩展时，可以定义终结点 PIM 调用、用于保护该终结点的Microsoft Entra ID资源，以及扩展适用的 PIM 资源类型。

将 POST 请求发送到 Microsoft 图形 API beta 终结点以创建自定义扩展：

POST https://microsoftgraph.chinacloudapi.cn/beta/identityGovernance/privilegedAccess/customExtensions
Content-Type: application/json

以下示例为适用于组的 PIM 创建自定义扩展：

{
  "@odata.type": "#microsoft.graph.roleManagementCustomCalloutExtension",
  "displayName": "Role Assignment Ticket Validation",
  "description": "Validates ticket info provided by requestor against ServiceNow",
  "endpointConfiguration": {
    "@odata.type": "#microsoft.graph.httpRequestEndpoint",
    "targetUrl": "https://api.contoso.com/webhooks/entra-role-assignments"
  },
  "clientConfiguration": {
    "@odata.type": "#microsoft.graph.customExtensionClientConfiguration",
    "timeoutInMilliseconds": 10000,
    "maximumRetries": 3
  },
  "authenticationConfiguration": {
    "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
    "resourceId": "api://api.contoso.com/00001111-aaaa-2222-bbbb-3333cccc4444"
  },
  "resourceType": "entraGroups",
  "customAttributes": []
}

Note

对于该代码片段中的资源 ID，请输入要使用的自己的 ID。

下表描述了自定义扩展 API 模型中的关键字段：

领域	类型	Description
`displayName`	String	在管理界面中为自定义扩展显示的友好名称。
`description`	String	自定义扩展的作用的说明。
`endpointConfiguration.targetUrl`	String	接收自定义扩展调用的 HTTPS 终结点。
`clientConfiguration.timeoutInMilliseconds`	Integer	PIM 等待终结点响应的最长时间。
`clientConfiguration.maximumRetries`	Integer	如果调用失败，重试次数上限。
`authenticationConfiguration.resourceId`	String	用于保护该端点的 Microsoft Entra 应用程序 ID URI。
`resourceType`	String	标识该扩展适用的 PIM 提供程序。

成功的响应返回具有创建自定义扩展对象的 HTTP 201 Created 状态代码。

在门户中创建自定义扩展

还可以使用Microsoft Entra 管理中心创建自定义扩展：

请以至少特权角色管理员的身份登录到Microsoft Entra 管理中心。
转到 Identity governance>Privileged Identity Management>Custom Extensions。
选择“创建自定义扩展”。
在 “基本信息 ”选项卡上，输入自定义扩展的名称、说明和资源类型。
在 “终结点配置 ”选项卡上，输入自定义扩展终结点的目标 URL、超时和最大重试次数。
在 “API 身份验证 ”选项卡上，选择保护自定义扩展终结点的应用程序注册。
在“ 审阅 + 创建 ”选项卡上，查看配置，然后选择“ 创建”。

创建自定义扩展后，它将显示在 “自定义扩展” 列表中。

创建后在 Privileged Identity Management 中可用的自定义扩展列表

将自定义扩展链接到 PIM 角色设置

接入自定义扩展后，请将其关联到每个需要 PIM 在激活时调用该扩展的角色的角色设置中。若要更新组的角色设置，需要该组的“所有者”角色。

链接到 PIM 中“组”的角色设置

若要将自定义扩展链接到组角色，请执行以下步骤：

登录到 Microsoft Entra 管理中心。
转到 Identity governance>Privileged Identity Management。
选择组。
选择目标组并打开其角色管理体验。
选择 “设置” 以查看组的可用角色。
选择要配置的角色，例如 “所有者 ”或“ 成员”，然后打开角色设置。
选择编辑。
选中“ 需要预审批自定义扩展才能激活”复选框。
选择要链接到此角色的自定义扩展。
选择 “保存” 以应用更新的角色设置。

保存后，角色设置详细信息页确认自定义扩展已链接。

你可以按照类似的流程将自定义扩展关联到 Azure 资源角色和 Microsoft Entra 目录角色。

验证角色激活流程

完成配置后，通过激活角色并确认 PIM 将请求发送到 API 并强制实施决策，验证自定义扩展是否按预期工作。

以符合角色资格的用户身份登录到 Microsoft Entra 管理中心。
转到 Privileged Identity Management 并激活配置了自定义扩展的角色。
提供所需的理由和票证信息。
提交激活请求。
验证 API 终结点是否从 PIM 接收 POST 请求。
确认 PIM 会执行您的自定义扩展返回的决策：
- 已批准：激活通过正常的 PIM 工作流进行，包括任何其他审批步骤。
- AutoApproved：激活继续进行，无需手动 PIM 批准。
- 被拒绝：激活被阻止，来自 API 响应的原因消息会显示在 PIM UI 中。
以下示例展示了一个因自定义扩展验证了票证信息而被拒绝的激活：

Last updated on 2026-07-02