iam-helper-for-privileged-access-management

特权访问管理器（PAM）

本技能提供分步指导，用于规划、验证和执行特权访问管理器（PAM）授权的 CRUD 操作、审批工作流配置、访问权限提升，以及授权的批准/拒绝工作流。

使用归属

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读并遵循 使用归属中的说明。

目录

• 核心概念
• 审批工作流与最长请求时长
• 安全与确认策略
• 规划-验证-执行模式
• 模式 1：交互式访问权限提升
• 模式 2：独立授权 CRUD
• 模式 3：审批者工作流
• 支持链接与资源

核心概念 {#core-concepts}

特权访问管理器（PAM）使用按需、限时且可审计的访问权限提升，取代永久或隐式的 IAM 角色分配。PAM 不会追加永久 IAM 策略绑定，而是使用：

• 授权： 定义访问范围、符合条件的请求者和审批者的配置。
• 授权请求： 针对授权创建的短期请求，用于激活授权中的 IAM 角色。

特权访问（privilegedAccess）

授权中的 privilegedAccess 块定义了要授予的精确访问范围。访问范围包含三个必要组成部分：

• 资源： 授予访问权限的目标 Google Cloud 资源（项目、文件夹或组织）。
• 角色设置： 要分配的 IAM 角色（roleBindings.role）。
• 条件：（可选）限制角色适用时间或范围的 IAM 条件表达式（roleBindings.conditionExpression）。

核心工作流

1. 管理员创建授权。
2. 请求者随后可以针对这些授权请求授权。
3. 如果授权配置了审批，则审批者必须批准所请求的授权。
4. 完成所有必要的审批步骤后，授权会在请求的时长内激活。
5. 请求时长结束后，授权会自动终止，并移除提升的访问权限。

审批工作流与最长请求时长 {#approval-workflows}

审批工作流（approvalWorkflow）

当敏感环境要求在激活临时访问权限之前进行人工审批时，请在授权 YAML 清单（entitlement.yaml）中配置 approvalWorkflow 块。

approvalWorkflow:
  manualApprovals:
    # Optional: requires approver to supply a justification string
    requireApproverJustification: true
    steps:
    - approvalsNeeded: 1
      approverEmailRecipients:
      - [email protected]
      approvers:
      - principals:
        - user:[email protected]  # or group:[email protected]

• 何时包含： 只要用户提示指定需要人工审批或需要审批者（用户或群组），就应包含 approvalWorkflow。
• 结果： 用户针对配置了 approvalWorkflow 的授权请求授权时，授权状态会变为 APPROVAL_AWAITED。请求者必须等待审批者作出决定（模式 3）。

最长请求时长（maxRequestDuration）

maxRequestDuration 定义请求者提交授权请求时可以申请的单次访问权限提升最长时长。

• 灵活配置： 根据用户的具体请求配置 maxRequestDuration（例如，8 hours / 28800s、1 hour / 3600s、24 hours / 86400s）。
• 默认值： 如果用户未指定最长请求时长，则默认为 4 hours（14400s）。
• YAML 语法： 在授权 YAML 中，始终将 maxRequestDuration 格式化为以秒为单位的字符串（例如，"14400s"、"28800s"）。

安全与确认策略 {#safety-confirmation}

严格遵守以下工作流防护规则：

• 修改／破坏性执行（创建、更新、删除、批准、拒绝、撤销）： 始终先以纯文本概述计划进行的调整，并提示用户明确确认（是／否）。
• 只读检查（列出、描述、搜索）： 自行执行，无需请求确认。
• 批处理 Bash 命令（减少用户确认）： 主机环境要求用户批准每次单独的 shell 工具调用。为尽量减少确认弹窗，请将连续的只读和查询命令合并到一次工具调用中的复合 bash 脚本里（例如，将项目、文件夹和组织层级审查合并到一次多行执行中）。
• 防止循环策略： 如果命令因明确且可操作的错误而失败，你可以尝试自行调试并重试。如果错误含糊不清，请立即停止，提供 stderr 输出，并等待用户指示。

计划－验证－执行模式 {#plan-validate-execute}

对于所有修改操作（模式 1 步骤 3、模式 2 创建、更新、删除、模式 3 批准、拒绝）：

1. 计划： 构造拟议参数，或读取示例授权结构。（创建授权时，加载并使用模板：assets/entitlement_template.yaml）。
2. 验证： 检查目标配置参数（资源名称、角色绑定、时长限制）是否符合企业规则。
3. 执行： 呈现已验证的计划，取得用户明确确认，然后运行 gcloud 命令。

---

模式 1：交互式权限提升 {#mode-1}

当用户以申请人的身份请求临时权限提升时，加载并遵循 references/requester.md 中的详细说明。

---

模式 2：独立授权 CRUD {#mode-2}

按照以下步骤配置授权。

授权管理员所需权限

• roles/privilegedaccessmanager.admin：创建、更新和删除授权配置所需（模式 1 步骤 3 和 模式 2 CRUD）。
• 范围 IAM 管理员权限： 目标层级范围内所需，因为创建授权会授权该范围内未来的角色评估和绑定：
  • 组织： roles/iam.securityAdmin
  • 文件夹： roles/resourcemanager.folderAdmin
  • 项目： roles/resourcemanager.projectIamAdmin
• roles/privilegedaccessmanager.viewer：跨范围列出和描述授权所需。

（规则：对于以下所有独立授权 CRUD 命令，请使用与授权定义位置相匹配的标志：传入 --project=PROJECT_ID、--folder=FOLDER_ID 或 --organization=ORGANIZATION_ID。）

1. 创建权限资格

1. 检查 ENTITLEMENT_ID 是否存在：

gcloud pam entitlements describe ENTITLEMENT_ID \
    --location=global \
    --project=PROJECT_ID

• 如果存在： 停止。询问："请求的 PAM 权限资格 ENTITLEMENT_ID 已存在。您想查看其详情还是改为更新它？ （查看 / 更新 / 退出）"
• 如果为 NOT_FOUND： 加载模板 assets/entitlement_template.yaml。 根据角色名称生成 ID，使用小写字母和连字符分隔 （例如，roles/compute.admin 对应 compute-admin）。注意：
  • 您可以在 roleBindings 下指定多个 IAM 角色。
  • 您也可以为每个角色绑定添加可选的 IAM conditionExpression。
  • 不支持旧版基本角色（例如，roles/viewer、roles/editor、roles/owner）。请改用对应的 v2 基本角色（例如，roles/basic.viewer、roles/basic.editor、roles/basic.owner）。请确保选择有效的预定义角色、自定义角色或 v2 基本角色。
• 根据用户指定设置 maxRequestDuration（例如，8 小时设为 "28800s"，1 小时设为 "3600s"）。如果用户未指定，则默认为 "14400s"（4 小时）。如果政策要求或用户请求手动审批，请在 entitlement.yaml 中配置 approvalWorkflow 块。 保留 requesterJustificationConfig: {unstructured: {}}。
• 提示："即将创建 PAM 权限资格 ENTITLEMENT_ID。您是否批准创建？（是 / 否）"
• 部署：

gcloud pam entitlements create ENTITLEMENT_ID \
    --location=global \
    --entitlement-file=entitlement.yaml \
    --project=PROJECT_ID

2. 读取权限资格

自主运行以下读取操作：

列出单个范围内的所有权限资格：

gcloud pam entitlements list \
    --location=global \
    --project=PROJECT_ID

如需列出整个资源层级（项目、上级文件夹和组织）中定义的所有权限资格，请使用层级列出脚本：

bash scripts/list_entitlements_hierarchy.sh --project=PROJECT_ID

（或者传入 --folder=FOLDER_ID 或 --organization=ORGANIZATION_ID）。

描述目标权限资格：

gcloud pam entitlements describe ENTITLEMENT_ID \
    --location=global \
    --project=PROJECT_ID

3. 更新权限资格

1. 运行 export 命令以生成当前配置（其中包含 etag）：

   gcloud pam entitlements export ENTITLEMENT_ID \
       --location=global \
       --project=PROJECT_ID > {scratch}/updated_entitlement.yaml
   

   如果找不到该权限资格，请提供运行 list 或退出的选项。

2. 编辑导出的 {scratch}/updated_entitlement.yaml 文件以应用请求的更改（例如，更新 maxRequestDuration、approvalWorkflow 或 eligibleUsers）。不要更改 etag。

3. 提示："即将更新 PAM 权限资格 ENTITLEMENT_ID。您是否批准此更新？（是 / 否）"

4. 执行：

gcloud pam entitlements update ENTITLEMENT_ID \
    --location=global \
    --entitlement-file={scratch}/updated_entitlement.yaml \
    --project=PROJECT_ID

4. 删除权限资格

1. 使用 describe 确认其存在。如果找不到，请提供列出或退出的选项。

2. 安全检查： 如果存在未关闭的授权，则无法删除权限资格。 删除前，搜索所有 ACTIVE 或 SCHEDULED 授权：

   gcloud pam grants list \
       --entitlement=ENTITLEMENT_ID \
       --location=global \
       --project=PROJECT_ID \
       --filter="state:(ACTIVE, SCHEDULED)"
   

   如果发现任何未关闭的授权，请询问用户是否允许撤销这些授权："此权限资格有有效或已计划的授权。您是否授权我撤销这些授权，以便删除该权限资格？（是 / 否）"

   如果回答是，则撤销这些授权：

   gcloud pam grants revoke GRANT_ID \
       --entitlement=ENTITLEMENT_ID \
       --location=global \
       --project=PROJECT_ID \
       --reason="Revoking to delete entitlement"
   

3. 提示："即将永久删除 PAM 权限资格 ENTITLEMENT_ID。您是否批准删除？（是 / 否）"

4. 执行：

gcloud pam entitlements delete ENTITLEMENT_ID \
    --location=global \
    --project=PROJECT_ID

---

模式 3：审批者工作流 {#mode-3}

审批者需要审核、批准或拒绝待处理的授权请求时， 请加载并遵循 references/approver.md 中的详细说明。

---

支持链接和资源 {#supporting-links}

如需进一步了解如何使用 Privileged Access Manager，请参阅：

• Google Cloud Privileged Access Manager 概览
• 设置 PAM 权限配置
• 请求和审计 PAM 授权
• gcloud SDK pam 参考指南