SWOT PAM Troubleshooting Runbook & FAQ

Actionable solutions to common operational questions, connection failures, authentication edge cases, and emergency recovery runbooks.

1. Authentication, Password & MFA Troubleshooting

Q: A user lost their MFA authenticator app. How do we reset it?

System administrators can reset a user's MFA state directly from the Users management console:

Go to Users in the left sidebar.
Locate the affected user and click Edit User.
Click Reset MFA Enrollment. The user's secret key is cleared and they will be prompted to re-enroll a new TOTP authenticator app on their next login.

Q: An account is locked due to too many failed password attempts.

Accounts are automatically locked for 15 minutes after 5 consecutive failed password attempts. An administrator can unlock the account immediately:

SQL Immediate Account Unlock

-- Connect to the PostgreSQL database and clear lockout
UPDATE users 
SET failed_login_attempts = 0, locked_until = NULL 
WHERE username = 'affected_user';

2. SSH Connection & Terminal Troubleshooting

Q: Native SSH client reports "Connection refused" on port 2222.

Verify that the SSH proxy container is healthy and that port 2222 is open on the host firewall:

Diagnostics Command

# Check if SSH proxy container is running
docker compose ps ssh-proxy

# View live proxy logs
docker compose logs -f ssh-proxy

# Test local port reachability
nc -zv 127.0.0.1 2222

3. Windows RDP & RemoteApp Troubleshooting

Q: Native mstsc reports an untrusted server certificate error.

In corporate environments with SSL inspection or self-signed gateway certificates, client machines should trust the SWOT PAM Gateway Root CA. Alternatively, if connecting via temporary test environments, bypass strict certificate checking by checking "Connect and don't ask again" in the Remote Desktop Connection dialog.

4. Database Proxy & Query Troubleshooting

Q: Connecting with DBeaver to port 5454 fails with "Authentication failed".

Ensure you are supplying your authentication identity using the composite username syntax:

DBeaver Username Configuration

# Username field format:
<pam_user>#<target_db_name_or_id>

# Example:
johndoe#prod_postgres_billing

# Password:
Your SWOT PAM account password + your 6-digit TOTP code

5. Emergency Break-Glass Runbook

Catastrophic Outage Recovery

In the event that the central SWOT PAM cluster is completely unreachable, designated security officers can decrypt the offline vault backup using the master key.

Execute the emergency decryption utility directly against the encrypted database backup:

Offline Vault Extraction Runbook

# 1. Export encrypted vault records from Postgres snapshot
node scripts/emergency-vault-access.mjs --extract --output vault_dump_encrypted.json

# 2. Decrypt with physical split key custodians (requires Dual Authorization)
node scripts/emergency-vault-access.mjs --decrypt \
  --input vault_dump_encrypted.json \
  --key-custodian-1 "KEY_PART_A" \
  --key-custodian-2 "KEY_PART_B" \
  --out-clear secrets_emergency_unlocked.txt