iam-helper-for-privileged-access-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Privileged Access Manager (PAM)

This skill provides step-by-step guidance for planning, validating, and executing Privileged Access Manager (PAM) entitlement CRUD operations, approval workflow configurations, access elevations, and grant approval/denial workflows.

本技能为Privileged Access Manager (PAM)权限的CRUD操作、审批工作流配置、权限提升以及授权审批/拒绝工作流提供分步指导，涵盖规划、验证和执行环节。

Core Concepts {#core-concepts}

核心概念 {#core-concepts}

Privileged Access Manager (PAM) replaces permanent or ambient IAM role assignments with on-demand, time-bound, and audited access elevations. Rather than appending permanent IAM policy bindings, PAM uses:

Entitlements: Configurations defining access scopes, eligible requesters, and approvers.
Grants: Short-lived requests created against entitlements to activate the entitlement's IAM roles.

Privileged Access Manager (PAM) 以按需、限时且可审计的权限提升替代永久或默认的IAM角色分配。它不会添加永久IAM策略绑定，而是采用以下机制：

权限（Entitlements）： 定义访问范围、符合条件的请求者和审批人的配置。
授权（Grants）： 基于权限创建的短期请求，用于激活权限对应的IAM角色。

Privileged Access (

privilegedAccess

)

特权访问（

privilegedAccess

）

The

privilegedAccess

block in an entitlement defines the precise access scope that will be granted. An access scope comprises three essential components:

Resource: The target Google Cloud resource (Project, Folder, or Organization) where access is granted.
Role Setup: The IAM role (
```
roleBindings.role
```
) to be assigned.
Condition: (Optional) An IAM condition expression (
```
roleBindings.conditionExpression
```
) restricting when or where the role applies.

权限中的

privilegedAccess

块定义了将被授予的精确访问范围。访问范围包含三个核心组件：

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

Core Workflow

核心工作流

Administrators create Entitlements.
Requesters can then request Grants against these entitlements.
If the entitlement is configured with approvals, then an approver must approve the requested grant.
Once all necessary approval steps are completed, the grant is activated for the requested time.
The grant automatically ends after the requested duration has elapsed, and the elevated access is removed.

管理员创建权限。
请求者可基于这些权限申请授权。
如果权限配置了审批要求，则审批人必须批准该授权请求。
完成所有必要的审批步骤后，授权将在请求的时长内生效。
请求时长结束后，授权自动终止，提升的权限被移除。

Approval Workflows & Max Request Duration {#approval-workflows}

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

Approval Workflows (

approvalWorkflow

)

审批工作流（

approvalWorkflow

）

When sensitive environments require human approval before temporary access is activated, configure the

approvalWorkflow

block in the entitlement YAML manifest (

entitlement.yaml

yaml

approvalWorkflow:
  manualApprovals:
    # Optional: requires approver to supply a justification string
    requireApproverJustification: true
    steps:
    - approvalsNeeded: 1
      approverEmailRecipients:
      - approver@example.com
      approvers:
      - principals:
        - user:db-lead@my-company.com  # or group:sre-leads@my-company.com

When to include: Include
```
approvalWorkflow
```
whenever the user prompt specifies that manual approval or an approver (user or group) is required.
Outcome: When a user requests a grant against an entitlement with
```
approvalWorkflow
```
, the grant transitions to
```
APPROVAL_AWAITED
```
. Requesters must await an Approver's decision (
```
Mode 3
```
).

当敏感环境要求在临时权限激活前进行人工审批时，需在权限YAML清单（

entitlement.yaml

）中配置

approvalWorkflow

块。

yaml

approvalWorkflow:
  manualApprovals:
    # 可选：要求审批人提供理由字符串
    requireApproverJustification: true
    steps:
    - approvalsNeeded: 1
      approverEmailRecipients:
      - approver@example.com
      approvers:
      - principals:
        - user:db-lead@my-company.com  # 或 group:sre-leads@my-company.com

配置时机： 当用户提示明确要求人工审批或指定审批人（用户或群组）时，需包含
```
approvalWorkflow
```
。
执行结果： 当用户针对配置了
```
approvalWorkflow
```
的权限申请授权时，授权状态将变为
```
APPROVAL_AWAITED
```
，请求者需等待审批人的决策（对应模式3）。

Max Request Duration (

maxRequestDuration

)

最长请求时长（

maxRequestDuration

）

maxRequestDuration

defines the maximum single access elevation timeframe a requester may ask for when placing a grant request.

Flexible Configuration: Configure
```
maxRequestDuration
```
according to the user's specific request (e.g.
```
8 hours
```
/
```
28800s
```
,
```
1 hour
```
/
```
3600s
```
,
```
24 hours
```
/
```
86400s
```
).
Default Value: If the user does NOT specify a maximum request duration, default to
```
4 hours
```
(
```
14400s
```
).
YAML Syntax: Always format
```
maxRequestDuration
```
as a string in seconds in the entitlement YAML (e.g.,
```
"14400s"
```
,
```
"28800s"
```
).

maxRequestDuration

定义了请求者申请授权时可请求的单次权限提升最长时长。

灵活配置： 根据用户的具体请求配置
```
maxRequestDuration
```
（例如：
```
8 hours
```
/
```
28800s
```
、
```
1 hour
```
/
```
3600s
```
、
```
24 hours
```
/
```
86400s
```
）。
默认值： 如果用户未指定最长请求时长，默认设置为
```
4 hours
```
（
```
14400s
```
）。
YAML语法： 在权限YAML中，
```
maxRequestDuration
```
必须格式化为秒数的字符串（例如：
```
"14400s"
```
、
```
"28800s"
```
）。

Safety & Confirmation Strategy {#safety-confirmation}

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

Adhere strictly to these workflow guards:

Modifying / Destructive Executions (Create, Update, Delete, Approve, Deny, Revoke): Always present a plain-text summary of the planned adjustments and prompt the user for explicit confirmation (Yes/No).
Read-Only Inspections (List, Describe, Search): Run autonomously without requesting confirmation.
Batching Bash Commands (Reduce User Confirmations): The host environment requires user approval for every individual shell tool call. To minimize confirmation popups, combine sequential read-only and lookup commands into a single compound bash script within one tool call (e.g., combining project, folder, and organization hierarchy audits into a single multiline execution).
Anti-Loop Strategy: If a command fails with a clear, actionable error, you may attempt to self-debug and retry. If the error is ambiguous, halt immediately, present the stderr output, and await user direction.

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

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

Plan-Validate-Execute Pattern {#plan-validate-execute}

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

For all modifying actions (Mode 1 Step 3, Mode 2 Create, Update, Delete, Mode 3 Approve, Deny):

Plan: Construct the proposed parameters or read the sample entitlement structure. (For entitlement creation, load and use the template: assets/entitlement_template.yaml).
Validate: Inspect the target configuration parameters (resource names, role bindings, duration limits) for compliance with corporate rules.
Execute: Present the validated plan, obtain explicit user confirmation, and run the
```
gcloud
```
command.

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

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

Mode 1: Interactive Access Elevation {#mode-1}

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

When the user requests temporary access elevation as a Requester, load and follow the detailed instructions in

references/requester.md

当用户作为请求者申请临时权限提升时，加载并遵循

references/requester.md

中的详细说明。

Mode 2: Standalone Entitlement CRUD {#mode-2}

模式2：独立权限CRUD操作 {#mode-2}

Follow these steps for entitlement configurations.

按照以下步骤进行权限配置。

Required Permissions for Entitlement Admins

权限管理员所需权限

```
roles/privilegedaccessmanager.admin
```
: Required to create, update, and delete entitlement configurations (
```
Mode 1 Step 3
```
and
```
Mode 2 CRUD
```
).
Scope IAM Admin Rights: Required on the target hierarchy scope because creating an entitlement authorizes future role evaluations and bindings on that scope:
- Organizations:
```
roles/iam.securityAdmin
```
- Folders:
```
roles/resourcemanager.folderAdmin
```
- Projects:
```
roles/resourcemanager.projectIamAdmin
```
```
roles/privilegedaccessmanager.viewer
```
: Required to list and describe entitlements across scopes.

(Rule: For all Standalone Entitlement CRUD commands below, use the flag matching where the entitlement is defined: pass
--project=PROJECT_ID
,
--folder=FOLDER_ID
, or
--organization=ORGANIZATION_ID
).

```
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. Create Entitlement

1. 创建权限

Check if
```
ENTITLEMENT_ID
```
exists:

bash

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

If Exists: Halt. Ask: "The requested PAM Entitlement
ENTITLEMENT_ID
already exists. Would you like to view its details or update it instead? (View / Update / Exit)"
If NOT_FOUND: Load the template assets/entitlement_template.yaml. Generate IDs in lowercase using hyphen separators derived from the role name (e.g.,
```
compute-admin
```
for
```
roles/compute.admin
```
). Note:
- You may specify multiple IAM roles under
```
roleBindings
```
  .
- You may also include an optional IAM
```
conditionExpression
```
  for each role binding.
- Legacy basic roles (e.g.,
```
roles/viewer
```
  ,
```
roles/editor
```
  ,
```
roles/owner
```
  ) are NOT supported. Instead, use their v2 basic role equivalents (e.g.,
```
roles/basic.viewer
```
  ,
```
roles/basic.editor
```
  ,
```
roles/basic.owner
```
  ). Ensure you select a valid predefined, custom, or v2 basic role.
Set
```
maxRequestDuration
```
based on user specification (e.g.
```
"28800s"
```
for 8 hours,
```
"3600s"
```
for 1 hour). If unspecified by the user, default to
```
"14400s"
```
(4 hours). If manual approval is specified by policy or requested by the user, configure the
```
approvalWorkflow
```
block in
```
entitlement.yaml
```
. Preserve
```
requesterJustificationConfig: {unstructured: {}}
```
.
Prompt: "You are about to create the PAM Entitlement
ENTITLEMENT_ID
. Do you approve this creation? (Yes/No)"
Deploy:

bash

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

检查
```
ENTITLEMENT_ID
```
是否存在：

bash

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

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

bash

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

2. Read Entitlements

2. 读取权限

Run these read operations autonomously:

List all entitlements at a single scope:

bash

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

To list all entitlements defined across the entire resource hierarchy (project, ancestor folders, and organization), use the hierarchy listing script:

bash

bash scripts/list_entitlements_hierarchy.sh --project=PROJECT_ID

(Or pass
--folder=FOLDER_ID
or
--organization=ORGANIZATION_ID
).

Describe target entitlement:

bash

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

自动执行以下读取操作：

列出单个范围下的所有权限：

bash

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

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

bash

bash scripts/list_entitlements_hierarchy.sh --project=PROJECT_ID

(或传递
--folder=FOLDER_ID
或
--organization=ORGANIZATION_ID
)

描述目标权限：

bash

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

3. Update Entitlement

3. 更新权限

Run the

export

command to generate the current config (which includes the

etag

bash

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

If missing, offer to run

list

or exit.

Edit the exported
```
{scratch}/updated_entitlement.yaml
```
file to apply the requested changes (e.g., updating
```
maxRequestDuration
```
,
```
approvalWorkflow
```
, or
```
eligibleUsers
```
). Do not alter the
```
etag
```
.
Prompt: "You are about to update the PAM Entitlement
ENTITLEMENT_ID
. Do you approve this update? (Yes/No)"
Execute:

bash

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

运行

export

命令生成当前配置（包含

etag

）：

bash

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

如果权限不存在，提供列出权限或退出的选项。

编辑导出的
```
{scratch}/updated_entitlement.yaml
```
文件，应用请求的更改（例如：更新
```
maxRequestDuration
```
、
```
approvalWorkflow
```
或
```
eligibleUsers
```
）。请勿修改
```
etag
```
。
提示："您即将更新PAM权限
ENTITLEMENT_ID
。是否批准此更新操作？（是/否）"
执行：

bash

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

4. Delete Entitlement

4. 删除权限

Verify existence using
```
describe
```
. If missing, offer list/exit.

Safety Check: An entitlement cannot be deleted if there are open grants. Before deleting, search for any

ACTIVE

SCHEDULED

grants:

bash

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

If any open grants are found, prompt the user for permission to revoke them: "There are active or scheduled grants on this entitlement. Do you authorize me to revoke them so the entitlement can be deleted? (Yes/No)"

If Yes, revoke them:

bash

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

Prompt: "You are about to permanently delete the PAM Entitlement
ENTITLEMENT_ID
. Do you approve this deletion? (Yes/No)"
Execute:

bash

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

使用
```
describe
```
命令验证权限是否存在。如果不存在，提供列出权限或退出的选项。

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

ACTIVE

或

SCHEDULED

状态的授权：

bash

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

如果发现未关闭的授权，提示用户是否允许撤销："此权限存在活跃或已调度的授权。是否授权我撤销这些授权以删除权限？（是/否）"

如果用户选择是，执行撤销：

bash

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

提示："您即将永久删除PAM权限
ENTITLEMENT_ID
。是否批准此删除操作？（是/否）"
执行：

bash

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

Mode 3: Approver Workflow {#mode-3}

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

When an Approver needs to review, approve, or reject pending grant requests, load and follow the detailed instructions in

references/approver.md

当审批人需要审核、批准或拒绝待处理的授权请求时，加载并遵循

references/approver.md

中的详细说明。

Supporting Links & Resources {#supporting-links}

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

For further information on working with Privileged Access Manager, refer to:

如需了解Privileged Access Manager的更多信息，请参考：

iam-helper-for-privileged-access-management

Original

Translation

Privileged Access Manager (PAM)

Privileged Access Manager (PAM)

Table of Contents

目录

Core Concepts {#core-concepts}

核心概念 {#core-concepts}

Privileged Access (privilegedAccess)

特权访问（privilegedAccess）

Core Workflow

核心工作流

Approval Workflows & Max Request Duration {#approval-workflows}

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

Approval Workflows (approvalWorkflow)

审批工作流（approvalWorkflow）

Max Request Duration (maxRequestDuration)

最长请求时长（maxRequestDuration）

Safety & Confirmation Strategy {#safety-confirmation}

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

Plan-Validate-Execute Pattern {#plan-validate-execute}

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

Mode 1: Interactive Access Elevation {#mode-1}

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

Mode 2: Standalone Entitlement CRUD {#mode-2}

模式2：独立权限CRUD操作 {#mode-2}

Required Permissions for Entitlement Admins

权限管理员所需权限

1. Create Entitlement

1. 创建权限

2. Read Entitlements

2. 读取权限

3. Update Entitlement

3. 更新权限

4. Delete Entitlement

4. 删除权限

Mode 3: Approver Workflow {#mode-3}

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

Supporting Links & Resources {#supporting-links}

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

Privileged Access (
`privilegedAccess`
)

特权访问（
`privilegedAccess`
）

Approval Workflows (
`approvalWorkflow`
)

审批工作流（
`approvalWorkflow`
）

Max Request Duration (
`maxRequestDuration`
)

最长请求时长（
`maxRequestDuration`
）