Support Impersonation System via JWT

[agentphoenix]

Overview

Build a centralized authentication system that allows support agents to securely impersonate users on distributed Nova instances without requiring local support accounts on each instance.

Core Architecture:

• Central support application manages all support identities and generates short-lived JWTs
• Nova instances (separate Laravel apps on independent servers) validate JWTs and create temporary impersonation sessions
• Public keys distributed via existing "external content / phone home" infrastructure

Goals

• Enable support reps to access any Nova instance as any user for troubleshooting
• Eliminate need for support accounts on each distributed instance
• Maintain strong security with audit trails and restricted permissions
• Support seamless key rotation without service disruption

Components

1. Central Support Application

Responsibilities:

• Authenticate support agents (SSO/MFA)
• Provide UI for instance/user selection with reason capture
• Generate signed JWT tokens (RS256, 5-minute expiry)
• Redirect support agents to target instance with token
• Maintain audit logs of all impersonation events
• Manage cryptographic key pairs (private + public)
• Distribute public keys to instances via API

Key Features:

• Database-backed key management system
• Key rotation with grace period support
• Instance registry with heartbeat monitoring
• Comprehensive audit trail

2. Nova Instances

Responsibilities:

• Accept and validate JWT tokens from central app
• Verify signature, issuer, audience, and expiration
• Enforce single-use tokens via JTI tracking
• Create impersonation sessions with user context
• Display visible "support mode" banner
• Log all impersonation activity locally
• Sync public keys from central app weekly
• Send notification to impersonated user for further visibility

Key Features:

• Multi-key validation support (handles rotation gracefully)
• Rate limiting on impersonation endpoint
• Action restrictions during impersonation (password changes, deletions, etc.)
• Session timeout enforcement (shorter than normal sessions)

Security Model

Token Security:

• Asymmetric RS256 signing (4096-bit keys)
• 5-10 minute token lifetime
• Single-use enforcement via JTI tracking
• Required claims: iss, aud, sub, iat, exp, jti, support metadata

Key Management:

• Private keys stored only in central app database
• Public keys distributed to instances via authenticated API
• Support for multiple valid keys simultaneously (rotation grace period)
• Database storage enables dynamic updates without redeployment

Transport Security:

• POST requests with token in body (not query string)
• HTTPS required for all communication
• Instance authentication via bearer token or ID+secret
• Clock skew tolerance (60 seconds)

Session Security:

• Session regeneration after impersonation login
• Visible banner on all pages during impersonation
• Restricted actions (configurable)
• Automatic timeout (e.g., 30 minutes of inactivity)
• Complete session invalidation on exit

Implementation Details

Database Schema

Central App:

impersonation_keys
- key_id (unique identifier, e.g., '2024-11')
- public_key (PEM format)
- private_key (encrypted, only for current key)
- activated_at
- expires_at (nullable, for grace period)
- is_current (boolean)
- rotation_reason

impersonation_logs
- jti (token ID)
- key_id
- support_user_id
- instance_id
- target_user_id
- reason
- timestamps

Nova Instances:

external_keys
- id
- public_key
- activated_at
- expires_at
- synced_at

used_impersonation_tokens
- jti (primary key)
- external_key_id
- expires_at
- used_at

Key Endpoints

Central App:

• GET /support/impersonate/select - UI for selecting instance/user
• POST /support/impersonate/generate - Generate JWT and redirect
• GET /api/impersonation/keys - Distribute public keys to instances (authenticated)

Nova Instances:

• POST /support/impersonate - Accept token, validate, create session
• POST /support/stop - End impersonation session
• Auto-sync keys via scheduled job

Token Claims Structure

{
  "iss": "https://anodyne-productions.com/admin/support",
  "aud": "instance-alpha",
  "sub": "42",
  "iat": 1732700000,
  "exp": 1732700300,
  "jti": "hex-random-64-chars",
  "support": {
    "id": "sup_123",
    "name": "Jane Smith",
    "email": "jane@support.example.com",
    "reason": "Debugging character issue"
  }
}

Key Rotation Process

1. Generate new key pair via artisan command
2. Store in central app database, mark as current
3. Set expiration on previous key (3-month grace period)
4. Instances automatically sync new keys via weekly job
5. Monitor key usage and instance sync status
6. Remove expired keys after grace period

Grace Period Benefits:

• Central app immediately signs with new key
• Nova instances accept tokens from both old and new keys
• Older Nova instances continue working until they sync
• Zero-downtime rotation

Monitoring & Auditing

Central App Metrics:

• Active impersonation sessions
• Key rotation history
• Instance sync status (last_key_sync_at)
• Failed token generation attempts
• Key usage by key_id

Nova Instance Metrics:

• Token validation failures (by reason)
• Rate limit hits
• Impersonation session duration
• Restricted action attempts
• Key sync failures

Audit Requirements:

• Who (support agent) accessed what (user account) when and why
• Full trail on both central app and instances
• Token reuse detection with alerts
• Failed validation attempts logged with IP

Dependencies

• PHP package: lcobucci/jwt (Laravel's JWT library of choice)
• Existing instance heartbeat/phone-home infrastructure
• HTTPS endpoints on all instances

Success Criteria

• Support agents can impersonate users on any instance without local accounts
• Token validation requires <100ms on instances
• Key rotation completes with zero service disruption
• All impersonation events logged with full audit trail
• Compromised key can be revoked within 24 hours across all instances
• Support banner visible on all pages during impersonation
• Critical actions blocked or require confirmation during impersonation
• Single-use token enforcement prevents replay attacks
• Rate limiting prevents brute force attacks on impersonation endpoint

Future Enhancements (Optional)

• Customer-approved access with PIN verification
• Fine-grained permission scopes (read-only, billing-only)
• Central verification API for real-time token validation
• Support session recording/playback for compliance
• Automated key rotation on schedule
• Customer notification on support access

Risks & Mitigations

Risk	Impact	Mitigation
Central app compromise	Critical - all instances vulnerable	SSO+MFA, strict access controls, HSM for key storage
Token interception	High - single user compromise	Short expiry (5min), HTTPS only, single-use enforcement
Key rotation failure	Medium - instances unable to validate	Multi-key validation, 3-month grace period, sync monitoring
Instance sync failure	Low - uses old keys until next sync	Daily sync attempts, manual sync command, alerting
JTI storage growth	Low - database bloat	Automated cleanup of expired tokens (7 days past expiry)

Testing Requirements

• Unit tests for token generation/validation
• Integration tests for full impersonation flow
• Security tests for token replay, tampering, expiry
• Load tests for concurrent impersonations
• Key rotation simulation with multiple instances
• Failure scenario testing (network issues, expired keys, etc.)