swissoid-back/REDIS_REQUIREMENTS.md

Redis Requirements for swissoid-back

Overview

swissoid-back requires Redis for managing authentication sessions and security tokens. Redis is used for:

1. Session Storage: Storing user session data after successful authentication
2. JTI Replay Prevention: Ensuring single-use of JWT tokens to prevent replay attacks
3. Transit Token Storage: Temporary tokens during the login flow (60-second TTL)

Redis Configuration

The Redis client in swissoid-back expects the following configuration from appConfig:

• redisHost: Redis server hostname (default: 'localhost')
• redisPort: Redis server port (default: 6379)
• redisPassword: Redis password (optional)
• redisUrl: Complete Redis URL (overrides host/port/password if provided)
• redisDb: Redis database number (default: 0)

Docker Deployment

See docker-compose.example.yml for a complete example. Here's the minimal Redis service configuration:

services:
  swissoid-redis:
    image: redis:latest
    container_name: swissoid-redis
    expose:
      - 6379
    volumes:
      - redis:/data
    restart: always
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 3

Environment Variables

When deploying an application using swissoid-back, provide these environment variables:

REDIS_HOST=swissoid-redis
REDIS_PORT=6379
REDIS_DB=0
# Or use a complete URL:
# REDIS_URL=redis://swissoid-redis:6379/0

Redis Data Structure

swissoid-back uses the following Redis key patterns:

• session:{sessionId}: User session data (TTL: 7 days by default)
• oidc_jti:{jti}: JTI tokens for replay prevention (TTL: 10 minutes)
• login_tx:{transitToken}: Transit tokens during login flow (TTL: 60 seconds)

Connection Handling

The Redis client includes:

• Automatic retry strategy with exponential backoff
• Connection health checks
• Error logging
• Ready state verification with ping test

Security Considerations

1. Network Isolation: Keep Redis on an internal network, not exposed to the internet
2. Password Protection: Use REDIS_PASSWORD in production environments
3. Data Persistence: Configure Redis volumes for session persistence across restarts
4. TTL Management: Sessions expire after 7 days by default (configurable via sessionTTL)