Privileged Access Management

Scope

Privileged work is where trust can disappear fastest if controls are informal. This guide keeps the public-safe control model and removes private implementation and route detail.

Step-by-step guides for managing vaults, credentials, checkout/checkin, break-glass, and rotation.

Related documents: - Architecture: docs/architecture/pam.md - Functional: docs/functional/pam.md - RBAC setup: docs/manual/roles-permissions.md - Agent job management: docs/manual/host-agent-management.md

Vault Management

Creating a Vault

Required permission: pam_vaults.manage

• name must be unique within the organization (1-255 characters)
• Vault creation is subject to account-level quota limits (pam_vault quota)

Listing Vaults

You only see vaults where you have an explicit access grant (at view_vault level or higher). Account owners see all vaults.

Editing a Vault

Required permission: pam_vaults.manage + edit_vault vault access grant

Deleting a Vault

Required permission: pam_vaults.manage + edit_vault vault access grant

Deletion automatically cleans up associated vault access grants and legacy permissions.

Credential Management

Credentials (identities) are the actual privileged accounts stored in vaults – each has a username, encrypted secret, and optional host associations.

Adding a Credential

Required permission: pam_vaults.manage + edit_vault vault access grant on the target vault

The plaintext credential is encrypted immediately with AES-256-GCM v5 envelope encryption (600,000 PBKDF2 iterations) and never stored unencrypted. Older v4 records are still supported as a legacy fallback during reads and lazy upgrade. The credential field is not returned in any list or get response.

Bulk Importing Credentials

Use bulk import when migrating existing credential inventory into a vault.

• validate_only: true performs checks without writing records
• skip_existing: true ignores duplicate names in the target org
• Invalid host mappings or credential types are returned as per-item errors

Viewing a Credential (Metadata Only)

Returns metadata including rotation status, checkout state, and host associations. Does NOT return the plaintext credential. The provider_config field is redacted.

Revealing the Plaintext Credential

Required permission: pam_vaults.manage + view_credentials vault access grant

Returns the decrypted credential. This is audit-logged as a sensitive operation. View-only vault users (view_vault level) cannot reveal credentials.

UI behavior: The Reveal button (eye icon) is only visible to users with pam_vaults.manage permission. Users without this permission will not see the button in either the card or table view.

Editing a Credential

Required permission: pam_vaults.manage + edit_vault vault access grant

Changing rotation_interval_days recalculates the next rotation date. Set is_active: false to deactivate a credential without deleting it.

Deleting a Credential

Required permission: pam_vaults.manage + edit_vault vault access grant

Checking Out Credentials

Checkout grants time-limited access to a decrypted credential. All usage is audit-logged.

Performing a Checkout

Required permission: pam_vaults.view + checkout vault access grant

• reason is mandatory (1-500 characters)
• duration_minutes defaults to 60, range 5-1440 (max 24 hours)

The response includes: - The decrypted credential - A session token (save this for checkin) - The session expiry timestamp

Checking In

Returns 204 No Content. If the credential has rotate_after_use enabled, the password is automatically rotated after checkin.

Viewing Your Active Checkouts

When a checkout is linked to a host, the page also shows Launch SSH and Launch Desktop. Those buttons open the standard Host Details or Remote Desktop flow using the existing PAM checkout token without putting it in the URL.

Workflow Automation

What Happens If You Don’t Check In

The session auto-expires at the deadline. The scheduler checks every 60 seconds for expired sessions. If rotate_after_use is enabled, the rotation still runs on expiry. The credential becomes available for other users after expiry.

Concurrency Rules

• By default, only one checkout at a time per credential (allow_concurrent_checkout: false)
• If concurrent checkout is enabled, the max_concurrent_sessions limit applies (default 1)

Break-Glass Emergency Access

Break-glass is for P1/P2 incidents when normal vault access grants are insufficient or unavailable.

Prerequisites

You must have the pam_vaults.break_glass permission. This is NOT included in any default role – it must be explicitly granted by an account owner.

Using Break-Glass

• reason must be at least 20 characters (detailed justification required)
• duration_minutes must be 15, 30, or 60 minutes
• Rate limited to 3 break-glass requests per minute

What Happens

1. Vault access grants are bypassed – you don’t need a vault-level grant
2. A time-limited session is created with a hard, non-extendable expiry
3. A critical notification is sent to ALL account admins in the organization
4. The decrypted credential is returned
5. When the session ends (checkin or timeout):
6. The credential is ALWAYS rotated, regardless of rotate_after_use setting
7. Full audit trail is recorded
8. The session cannot be extended – plan your work within the time limit

Rotation Management

Manual Rotation

Required permission: pam_vaults.manage + edit_vault vault access grant

The system resolves the rotation provider based on the credential configuration: - password/ssh_key/service_account with no explicit provider: os_account provider (dispatches agent jobs to change the password on all associated hosts) - api_token/certificate/snmp_: manual provider (fires an alert, sets status to awaiting_manual) - Explicit provider*: uses whatever rotation_provider is set on the credential

Automatic Rotation

Set rotation_interval_days on the credential (e.g., 30, 60, 90). The scheduler checks every 30 minutes for credentials past their next_rotation date and dispatches rotation automatically.

Failed rotations are retried up to 3 times with exponential backoff (1 hour, 4 hours, 24 hours). After 3 failures, a high-severity alert fires and retries stop (rotation_status set to failed_alerted).

Completing a Manual Rotation

When the manual rotation provider is used, the credential enters awaiting_manual status. After changing the credential externally:

This stores the new credential, resets the rotation status to confirmed, and recalculates the next rotation date.

Monitoring Rotation Status

Returns the current rotation status with per-host detail when applicable: - pending: rotation jobs dispatched, waiting for completion - confirmed: all hosts updated successfully - failed: all hosts failed - partial_failed: some hosts succeeded, some failed (check subtasks for detail) - awaiting_manual: manual provider waiting for operator to complete

Retrying Failed Session Rotations

If rotation failed after a checkout session ended:

Check rotation progress:

Vault Access Grants

Vault access grants control who can interact with specific vaults. They are separate from RBAC role permissions – having the pam_vaults.view role permission only gets you past the RBAC gate. You still need an explicit vault grant to access any vault’s data.

Exception: Account owners bypass vault grants automatically.

Access Levels

Each level includes all capabilities of lower levels:

Level	What You Can Do
view_vault	See the vault exists, view credential names and metadata
edit_vault	Edit vault settings, create/update/delete credentials, manage rotation
view_credentials	Reveal plaintext credential values
checkout	Checkout credentials for use

Granting Vault Access

Required permission: pam_access.manage

Grant to a specific user (IDP user ID):

Grant to a group (all group members get access):

Listing Vault Grants

Returns all active grants for the vault with enriched user/group names.

Revoking Vault Access

Soft-deletes the grant (sets is_active = false).

Viewing Your Vault Access

Returns all vaults you can access with your effective access level and whether the access comes from a direct grant or group membership.

Grant Precedence Rules

• Direct user grants take absolute precedence over group grants
• Among group grants, the highest access level wins
• Expired grants (expires_at in the past) are silently excluded
• The scheduler deactivates expired grants every 5 minutes

Setting Grant Expiry

Set expires_at on the grant to create time-limited access. Good for temporary access during incidents or projects. The grant is checked at request time, so even if the scheduler hasn’t run yet, an expired grant is rejected.

Session Monitoring

Viewing Session History

Returns the full session history for a credential: who checked it out, when, for how long, and the rotation status after checkin. Use active_only=true to see only current checkouts.

Viewing All Active Sessions

Required permission: pam_vaults.view

The Active Sessions tab on the Identities page shows all currently checked-out credentials across all vaults. This view supports server-side pagination with 50 sessions per page.

Response includes enriched data: user email, identity name, vault name, host hostname/IP, checkout reason, break-glass status. The status bar shows “Showing X of Y active sessions across all vaults” and page controls appear when there are more than 50 sessions. Tenant scoping is always enforced against the caller’s selected account/org context, including account-owner sessions. The same Launch SSH / Launch Desktop actions appear here only for sessions you personally own. Admins can monitor every row, but relaunch remains tied to the original checkout holder’s token.

Force Check-in: Users with pam_vaults.manage can force-checkin any session from this view. This immediately ends the session and triggers rotation if configured.

Reviewing PAM Compliance KPIs

Use this API to track: - overdue and failed rotations - pending/manual rotation backlog - recent checkout and break-glass activity - top overdue identities (with days_overdue)

Host Picker

When creating or editing a credential, the host association picker uses server-side search. Type in the search box to find hosts by hostname or IP address. Results are loaded from the server in real-time with a 300ms debounce delay.

Setting Legal Hold on Session Recordings

Required permission: session_recordings.legal_hold

When legal hold is active, the recording cannot be deleted by retention policies or manual deletion. Works for both terminal and desktop recordings. To clear the hold:

2026-04-09 Batch 06 Remediation Update

• The PAM “Active Checkouts” banner now shows hostnames from server-enriched checkout data when available.
• Vault-scoped actions (checkout/reveal/edit/rotate/delete) now align more closely with resolved vault grants in the UI, reducing cases where a button is shown but rejected by the backend.

2026-04-12 Batch 06 Remediation Update

• Active session admin view now enforces selected-account/org scope for all callers, including account owners.
• Rotation status APIs now return subtask summary counts plus last_error for faster operational triage.