PowerOn Gateway - Session Handling for Horizontal Scaling

Executive Summary

Status: ✅ READY FOR HORIZONTAL SCALING

The PowerOn Gateway uses a stateless, database-backed session architecture that supports horizontal scaling with load balancers. User sessions persist across multiple gateway instances without requiring sticky sessions or shared in-memory storage.

Architecture Overview

Session Management Approach

Authentication Method: JWT tokens stored in httpOnly cookies

Access token: auth_token cookie
Refresh token: refresh_token cookie
Tokens contain user context (userId, mandateId, sessionId)

Token Validation: Database-backed

All tokens stored in Token database table
Each request validates token against database
Token status: ACTIVE or REVOKED
No in-memory session storage (no Redis/Memcached)

Key Characteristics:

✅ Stateless backend design
✅ Database as single source of truth
✅ Cookie-based token transmission
✅ Independent token validation per instance

Load Balancer Configuration

Recommended Settings

Setting	Value	Notes
Session Affinity	NOT REQUIRED	Can use round-robin or least-connections
Health Checks	Standard HTTP	Standard endpoint health checks
Cookie Handling	Default	Browser handles cookies automatically
Sticky Sessions	NOT NEEDED	Gateway instances are stateless

Current cookie settings (configured in code):

path="/" - Available across all paths
samesite="strict" - CSRF protection
httponly=True - XSS protection
secure - Enabled when using HTTPS

No special load balancer cookie configuration required.

Deployment Requirements

Database Configuration

Requirements for Logical Database:

Single logical database instance (shared across all gateway instances)
Database must be accessible from all gateway instances
Database must support concurrent connections from multiple instances
Each gateway instance requires proper database connection pooling
Database should handle concurrent token validation queries efficiently

Token Table: Contains all session state

Token ID (jti)
User ID, Session ID, Mandate ID
Status (ACTIVE/REVOKED)
Expiration timestamps

Gateway Instance Configuration

Each gateway instance:

✅ Operates independently
✅ Validates tokens via database queries
✅ No shared state with other instances
✅ Can be added/removed without affecting active sessions

Key Points for Operations

✅ No sticky sessions required - Load balancer can distribute requests freely
✅ Shared logical database required - All instances access the same database
✅ Instances are independent - Can add/remove instances without downtime
✅ Sessions persist across instances - Users won't lose sessions during failover

Document prepared for Operations Center, Patrick Motsch, PowerON AG, 2026-01-11

3 KiB Raw Blame History