36. Hybrid Session Model for Long-Running Tasks

Architecture Decision Record: 36. Hybrid Session Model for Long-Running Tasks

36. Hybrid Session Model for Long-Running Tasks

Date: 2025-01-28

Status

Accepted

Category

Authentication & Authorization

Context

JWT-based authentication (ADR-0032) uses short-lived access tokens (15 minutes) for security, but this conflicts with long-running tasks:

• Batch ETL jobs running 6-12 hours
• Streaming WebSocket connections
• Background processors with persistent queues
• Scheduled reports generated over hours
• Real-time data pipelines

Challenges:

• 15-minute tokens inadequate for multi-hour tasks
• Client-side refresh complex for background processes
• Purely stateless JWT can’t be revoked mid-session
• Service principals need 30-day authentication

Current system: Stateless JWTs only (no server-side sessions).

Decision

Implement a Hybrid Session Model where standard users use stateless JWTs with client-side refresh, while service principals optionally use server-side sessions with automatic token refresh for long-running tasks.

Architecture

Distributed Session Consistency Flow

Mode 1: Stateless JWT (Default for Users):

• 15-minute access tokens
• 30-minute refresh tokens
• Client-side refresh logic
• No server-side storage

Mode 2: Hybrid Session (Service Principals):

• 15-minute access tokens (still short)
• 30-day refresh tokens stored in Redis
• Server-side automatic refresh before expiration
• Session TTL: 30 days with sliding window

Core Principles

1. JWT First: Always use JWTs for authentication (not opaque session IDs)
2. Selective Sessions: Only service principals use server-side sessions
3. Automatic Refresh: Server refreshes tokens before expiration
4. Sliding Window: Session TTL extends on activity
5. Instant Revocation: Server-side sessions can be revoked immediately
6. Redis Storage: Distributed session store for multi-replica support

Configuration

# Session Mode
AUTH_MODE=hybrid  # stateless for users, session for service principals
SESSION_BACKEND=redis
REDIS_URL=redis://localhost:6379/0

# Service Principal Sessions
SERVICE_PRINCIPAL_SESSION_ENABLED=true
SERVICE_PRINCIPAL_SESSION_TTL=2592000  # 30 days
SERVICE_PRINCIPAL_AUTO_REFRESH=true
SESSION_SLIDING_WINDOW=true
SESSION_REFRESH_THRESHOLD=300  # Refresh if expires in \<5 min

# User Sessions (optional)
USER_SESSION_TTL=86400  # 24 hours if enabled

Consequences

Positive Consequences

• Long-running task support (30-day sessions)
• Automatic refresh (no client complexity)
• Instant revocation capability
• Security maintained (still use short-lived access tokens)
• Audit trail (session activity logged)

Negative Consequences

• Redis dependency (infrastructure overhead)
• Complexity (two modes to maintain)
• Storage cost (session data in Redis)
• Potential session leakage if not cleaned up

Mitigation Strategies

• Redis HA setup (cluster mode), automatic TTL expiration
• Clear documentation on when to use each mode
• Monitoring: session count, memory usage, refresh failures
• Cleanup job for orphaned sessions

Alternatives Considered

1. Long-Lived JWTs: Rejected - cannot revoke, security risk
2. Sessions for All: Rejected - stateless architecture preferred for users
3. Stateless Only: Rejected - inadequate for long-running tasks
4. Token Exchange: Rejected - complex, requires admin credentials

Implementation

Session Data Structure:

@dataclass
class ServicePrincipalSession:
    session_id: str
    user_id: str  # service:batch-job
    access_token: str  # Current JWT
    refresh_token: str  # 30-day refresh token
    created_at: str
    last_accessed: str
    expires_at: str  # 30 days from last activity
    metadata: Dict[str, Any]

Session Manager (src/mcp_server_langgraph/auth/session.py):

class RedisSessionStore:
    async def create_session(self, user_id, tokens, ttl=2592000):
        session = ServicePrincipalSession(...)
        await redis.setex(f"session:{session_id}", ttl, session.json())

    async def get_session(self, session_id):
        data = await redis.get(f"session:{session_id}")
        return ServicePrincipalSession.parse_raw(data)

    async def refresh_if_needed(self, session_id):
        session = await self.get_session(session_id)
        if session.expires_in < 300:  # \<5 minutes
            new_tokens = await keycloak.refresh_token(session.refresh_token)
            session.access_token = new_tokens["access_token"]
            session.refresh_token = new_tokens["refresh_token"]
            await self.update_session(session)

Middleware (src/mcp_server_langgraph/auth/middleware.py):

async def get_current_user(request: Request):
    # Extract JWT from header
    token = extract_bearer_token(request)

    # Verify JWT
    payload = await auth.verify_token(token)

    # If service principal, check/refresh session
    if payload["sub"].startswith("service:"):
        session_id = request.headers.get("X-Session-ID")
        if session_id:
            await session_manager.refresh_if_needed(session_id)

    return payload

References

• Session Store: src/mcp_server_langgraph/auth/session.py (existing, to be enhanced)
• Middleware: src/mcp_server_langgraph/auth/middleware.py (to be updated)
• Related ADRs: ADR-0006, ADR-0032, ADR-0033
• External: Redis TTL, OAuth2 Refresh