/iam-helper-for-privileged-access-management

name: iam-helper-for-privileged-access-management
metadata:
  version: "1.0.2"
  category: Security
description: >-
  Manages the end-to-end lifecycle of on-demand, temporary access using
  Privileged Access Manager (PAM). Use when a user asks to create, read,
  update, or delete PAM entitlements, request temporary access, or
  approve/deny pending PAM grants. Do NOT use for permanent IAM policy
  bindings, troubleshooting IAM permission errors, or general Google Cloud
  resource provisioning.

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.

Usage Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read and follow the instructions in [Usage Attribution](references/attribution.md).

Table of Contents

• [Core Concepts](#core-concepts)
• [Approval Workflows & Max Request Duration](#approval-workflows)
• [Safety & Confirmation Strategy](#safety-confirmation)
• [Plan-Validate-Execute Pattern](#plan-validate-execute)
• [Mode 1: Interactive Access Elevation](#mode-1)
• [Mode 2: Standalone Entitlement CRUD](#mode-2)
• [Mode 3: Approver Workflow](#mode-3)
• [Supporting Links & Resources](#supporting-links)

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 (`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.

Core Workflow

1. Administrators create Entitlements. 2. Requesters can then request Grants against these entitlements. 3. If the entitlement is configured with approvals, then an approver must approve the requested grant. 4. Once all necessary approval steps are completed, the grant is activated for the requested time. 5. 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 (`approvalWorkflow`)

When sensitive environments require human approval before temporary access is activated, configure the `approvalWorkflow` block in the entitlement YAML manifest (`entitlement.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`).

Max Request Duration (`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"`).

Safety & Confirmation Strategy {#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.

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

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

1. **Plan:** Construct the proposed parameters or read the sample entitlement structure. (For entitlement creation, load and use the template: [assets/entitlement_template.yaml](assets/entitlement_template.yaml)). 2. **Validate:** Inspect the target configuration parameters (resource names,