Skip to content

Break-Glass Emergency Access

Section: Security | Article 22
Audience: System Administrators, Security Officers
Last Updated: 2026-04-06

Overview

RP-PAM uses a four-tier troubleshooting model. Normal operations use Tier 1 (web portal). Emergency access escalates through progressively more restricted tiers, each with its own security controls.

Tier Account When Used Security Level
Tier 1 Your normal admin account Day-to-day operations Standard (MFA + JWT)
Tier 2 rppam-monitor Elevated monitoring during incidents IP-restricted, read-only
Tier 3 rppam-emergency Full troubleshooting when portal is down FIDO2 key + QR password, time-limited, witnessed
Tier 4 Ravenphyre support session Vendor assistance Customer-initiated, scoped, time-limited

Important: Tier 3 (break-glass) access is the most sensitive access path in your RP-PAM deployment. The physical security procedures in this document must be followed exactly.

Tier 1: Web Portal (Normal Operations)

No special setup needed. System Administrators connect via the web portal at https://your-pam-server:7101. All actions are API-driven through the browser. This is the preferred method for 99% of administrative tasks.

Tier 2: Monitor Account

What It Is

A dedicated local account (rppam-monitor) on each RP-PAM node with read-only access to: - RP-PAM service status - Log files (specific paths only) - Health check endpoints

It cannot: stop/start services, read vault data, modify configuration, or execute arbitrary commands.

Setup

Generate monitor credentials:

Windows PowerShell: 

& "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-breakglass.exe" generate-monitor

Linux: 

sudo /opt/rppam/tools/rppam-breakglass generate-monitor

The tool outputs a username, password, and allowed IPs. Store the password in your vault or password manager.

Configuration

In rppam.config: 

{
  "breakGlass": {
    "monitorAccountEnabled": true,
    "monitorPasswordRotationDays": 7,
    "monitorAllowedIps": "10.0.0.0/24,192.168.1.100"
  }
}

Setting Description Default
monitorAccountEnabled Enable/disable the monitor account true
monitorPasswordRotationDays Auto-rotate password every N days 7
monitorAllowedIps IP addresses/CIDR ranges allowed to login 127.0.0.1

Security Controls

  • Login is rejected from any IP not in the monitorAllowedIps list
  • Password is rotated automatically every 7 days
  • Account has no shell access — can only query health endpoints and read logs
  • All login attempts are logged (successful and failed)

Tier 3: Emergency (Break-Glass) Account

What It Is

A one-time-use emergency account (rppam-emergency) for situations where the web portal is completely unavailable and Tier 2 monitoring is insufficient. This account has full local troubleshooting access to the RP-PAM service on the node where it is used.

Critical Security Controls

Control Detail
FIDO2 Hardware Key Required for production deployments. The physical key must be present at login.
QR Code Password A unique password encoded as a QR code, printed and sealed in a physical secure container.
60-Minute Session The session automatically terminates after 60 minutes. The account is locked after expiry.
Security Witness A security officer or second administrator must be physically present during use.
Full Recording Every command executed during the session is recorded to a tamper-evident log.
Immediate Alert All System Admins and Audit Reviewers receive a critical alert the moment the account is used.
No Network Access The break-glass account cannot reach Active Directory or Entra ID — it can only interact with the local RP-PAM service.

Initial Setup

Step 1: Generate emergency credentials

Windows PowerShell: 

& "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-breakglass.exe" generate-emergency

Linux: 

sudo /opt/rppam/tools/rppam-breakglass generate-emergency

The tool outputs: - Username: rppam-emergency - Password (raw text) - Password hash (for storage) - QR code data string - Whether FIDO2 is required

Step 2: Create the physical QR code

  1. Copy the QR code data string
  2. Generate a QR code image using any QR generator (online or offline)
  3. Print the QR code on paper
  4. Immediately delete the digital password from your screen and clipboard
  5. Place the printed QR code in a tamper-evident envelope
  6. Seal the envelope in a physical secure container (safe, locked cabinet, or security room)
  7. Record the container location in your organisation's security documentation

Step 3: Store the FIDO2 hardware key

  1. Enrol a FIDO2 hardware key (YubiKey, Google Titan, etc.) for the break-glass account
  2. Store the hardware key in the same secure container as the QR code
  3. A backup FIDO2 key should be stored in a separate secure location

Configuration

In rppam.config: 

{
  "breakGlass": {
    "emergencyAccountEnabled": true,
    "emergencySessionTimeoutMinutes": 60,
    "requireHardwareKey": true,
    "emergencyAllowedIps": "127.0.0.1"
  }
}

Setting Description Default
emergencyAccountEnabled Enable/disable the emergency account true
emergencySessionTimeoutMinutes Session auto-lock after N minutes 60
requireHardwareKey Require FIDO2 key (set false for prototype/lab) false
emergencyAllowedIps IPs allowed to login 127.0.0.1

Production deployments: Set requireHardwareKey: true. This is enforced in Release Candidate builds and later.

Lab/prototype deployments: Set requireHardwareKey: false to allow password-only login for testing.

Using the Break-Glass Account (Emergency Procedure)

When you need to use the Tier 3 emergency account, follow this procedure exactly:

Before Login

  1. Retrieve the sealed envelope containing the QR code and FIDO2 key from the secure container
  2. Verify the tamper-evident seal is intact. If the seal is broken, DO NOT USE the credentials — they may be compromised. Generate new credentials immediately.
  3. Ensure a security witness (security officer or second administrator) is physically present
  4. Document the reason for break-glass access in your incident log

During Login

  1. Scan the QR code to obtain the password
  2. Log in with username rppam-emergency and the scanned password
  3. Present the FIDO2 hardware key when prompted (production only)
  4. The 60-minute timer starts immediately
  5. Perform only the necessary troubleshooting actions
  6. The security witness should observe and note all actions taken

After Login

  1. When finished (or when the 60-minute timer expires), the session terminates automatically
  2. Physically destroy the used QR code:
    • Shred the paper using a cross-cut shredder
    • Burn the shredded material if your security policy requires it
    • The security witness must observe the destruction
  3. Generate new emergency credentials immediately: 
    & "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-breakglass.exe" generate-emergency
  4. Print a new QR code, seal in a new tamper-evident envelope, store in the secure container
  5. Document the incident:
    • Date and time of break-glass access
    • Who accessed the account
    • Who witnessed the access
    • Reason for access
    • Actions performed
    • Confirmation that old credentials were destroyed
    • Confirmation that new credentials were generated and sealed

Tier 4: Vendor Support Session

What It Is

A time-limited, customer-initiated support session that grants Ravenphyre support staff read-only diagnostic access. RP-PAM never initiates outbound connections to Ravenphyre support — the customer must explicitly create the session.

What Support Can See

  • System health and status
  • Log files
  • Configuration (non-sensitive values only)

What Support CANNOT See

  • Vault credentials
  • User passwords
  • Session recording contents
  • Audit log details

Creating a Support Session

Via the Web Portal: 1. Login as pam_admin 2. Navigate to Settings → Support 3. Click "Create Support Session" 4. Enter the reason for the support session 5. A Session ID is displayed — provide this to Ravenphyre support

Via the CLI:

Windows PowerShell: 

& "C:\Program Files\Ravenphyre\RP-PAM\tools\rppam-breakglass.exe" create-support `
  --initiated-by "admin@corp.local" `
  --reason "Investigating database connectivity issue, ticket #12345"

Linux: 

sudo /opt/rppam/tools/rppam-breakglass create-support \
  --initiated-by "admin@corp.local" \
  --reason "Investigating database connectivity issue, ticket #12345"

Via the REST API: 

Invoke-RestMethod -Uri "http://localhost:7101/api/v1/breakglass/support-session" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $adminJwt"; "Content-Type" = "application/json" } `
  -Body '{"reason":"DB connectivity issue, ticket #12345"}'

Session Limits

Setting Default
Maximum duration 120 minutes
Access scope Read-only diagnostics
Visibility Audit Reviewers can see the session in real time

Summary Checklist

  • [ ] Tier 2 monitor account generated and credentials stored
  • [ ] Tier 2 allowed IPs configured
  • [ ] Tier 3 emergency credentials generated
  • [ ] Tier 3 QR code printed and sealed in secure container
  • [ ] Tier 3 FIDO2 key enrolled and stored with QR code
  • [ ] Tier 3 backup FIDO2 key stored in separate location
  • [ ] requireHardwareKey set to true for production
  • [ ] Break-glass procedure documented in your organisation's security runbook
  • [ ] Security personnel aware of the witness requirement
  • [ ] Incident log template prepared for break-glass events

Next Steps

RP-PAM v1.0.0 — Copyright 2026 Ravenphyre. All rights reserved.