Skip to content

Session Management

Guide to monitoring and managing user sessions in Champa Intelligence.

Overview

Session management provides system control over active user sessions. This is critical for security, compliance, and troubleshooting authentication issues.

Session Architecture

Session Storage

graph LR
    A[User Login] --> B[Generate JWT]
    B --> C[Store in Redis]
    C --> D[Backup to PostgreSQL]

    E[User Request] --> F{Redis Available?}
    F -->|Yes| G[Validate from Redis]
    F -->|No| H[Validate from PostgreSQL]

    I[Logout] --> J[Delete from Redis]
    J --> K[Delete from PostgreSQL]
Hold "Alt" / "Option" to enable pan & zoom

Primary Storage: Redis (fast, in-memory)

Backup Storage: PostgreSQL (persistent, reliable)

Fallback: Application continues functioning if Redis is unavailable

Session Types

Regular Sessions

Characteristics: - Created on user login - TTL: 1 hour (configurable) - Extend on activity - Stored in Redis + PostgreSQL

Use Cases: - Web interface users - Interactive sessions - Normal authentication flow

Remember Me Sessions

Characteristics: - Extended TTL: 30 days (configurable) - Refresh token stored in cookie - Automatic session recreation - Survives browser restarts

Use Cases: - Trusted devices - Convenience for frequent users - Reduced login friction

API Token Sessions

Characteristics: - Long-lived JWT tokens - TTL: 7-365 days or never - Stateless (no Redis/PostgreSQL session) - Validated by JWT signature

Use Cases: - Programmatic access - CI/CD pipelines - Monitoring systems - Integration scripts

Session Configuration

TTL Settings

Environment Variables:

# Session Configuration
SESSION_TTL_HOURS=24              # Normal session lifetime
SESSION_TTL_REMEMBER_ME_DAYS=30   # Remember me lifetime
JWT_EXPIRATION_HOURS=24           # JWT token lifetime

Recommended Values:

Environment Normal TTL Remember Me TTL
Development 24 hours 30 days
Staging 12 hours 14 days
Production 8 hours 7 days
High-Security 4 hours Disabled

Troubleshooting

User Can't Stay Logged In

Symptoms: - User repeatedly logged out - Sessions expire too quickly - "Session expired" errors

Diagnosis:

# Check session TTL
curl http://localhost:8088/cache/api/stats \
  -H "Authorization: Bearer $ADMIN_TOKEN" | grep session_ttl

# Check user's sessions
curl http://localhost:8088/auth/sessions?user_id={user_id} \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Possible Causes:

  1. Short TTL - Increase SESSION_TTL_HOURS
  2. Clock skew - Sync server time
  3. Cookie issues - Check browser settings
  4. Redis evictions - Increase Redis memory

Next Steps

Support

For session management questions: