playchoo-auth

SwissOID authentication service for Playchoo. Manages OIDC login flow, session storage in Redis, and provides authentication endpoints for the Playchoo stack.

Architecture

• SwissOID Integration: Uses swissoid-back for OIDC authorization code flow
• Session Storage: Redis-backed sessions with HttpOnly cookies
• Shared Sessions: api.playchoo.com and app.playchoo.com share session state via Redis

Endpoints

• GET /login - Initiates SwissOID OIDC flow
• POST /oidc/callback - Handles SwissOID callback
• GET /oidc/finalize - Completes authentication and sets session cookie in first-party context
• GET /auth/status - Returns current authentication status
• POST /auth/logout - Destroys session
• GET /auth/debug - Debug endpoint to check session and cookie status
• GET /auth/ping - Connectivity test endpoint
• GET /healthz - Health check

Environment Variables

# SwissOID Configuration
SWISSOID_CLIENT_ID=playchoo
SWISSOID_CLIENT_SECRET=<your-secret>
SWISSOID_ISSUER=https://api.swissoid.com
SWISSOID_JWKS_URI=https://api.swissoid.com/.well-known/jwks.json
SWISSOID_TOKEN_ENDPOINT=https://api.swissoid.com/token
SWISSOID_AUTHORIZE_ENDPOINT=https://api.swissoid.com/authorize

# CORS
CORS_ALLOWED_ORIGIN=https://app.playchoo.com
CORS_CREDENTIALS=true
CORS_METHODS=GET,POST,OPTIONS
CORS_HEADERS=Content-Type,Authorization,Apollo-Require-Preflight,X-Requested-With,X-CSRF-Token
CORS_MAX_AGE=86400
SKIP_CORS=false

# Traefik / Deployment
REVERSE_DOMAIN=playchoo-auth
APPLICATION_DOMAIN_NAME=auth.playchoo.com

# Session Configuration
SESSION_COOKIE_NAME=playchoo_session
REFRESH_COOKIE_NAME=playchoo_refresh
SESSION_SECRET=<generate-random-secret>
STATE_SIGNING_SECRET=<generate-random-secret>
SESSION_TTL=7200
REFRESH_TTL=604800

# Redis (shared with py-playchoo-api)
REDIS_URL=redis://redis:6379

# RP Configuration
OIDC_REDIRECT_BASE_URL=https://auth.playchoo.com
RP_FRONTEND_URL=https://app.playchoo.com
RP_COOKIE_DOMAIN=.playchoo.com
POST_LOGIN_PATH=/dashboard

> When running the service directly on your host (outside Docker), override
> `REDIS_URL` to `redis://localhost:6379`. The Docker Compose files remap it to
> `redis://redis:6379` so the container can reach the shared Redis service.

For production deploys copy .env.prod to the target host as .env (the compose file loads ./.env) and populate it with environment-specific secrets from Vault before running the stack.

Local Development

npm install

# Ensure the shared Redis network exists (run once)
docker network create playchoo_redis_network || true

# Start the Redis service from py-playchoo-api (or attach your own instance to the same network)
(cd ../py-playchoo-api && docker compose -f docker-compose.dev.yml up redis)

# In a new terminal, start the auth service
npm run dev

The service will start on http://localhost:3700 and will reuse the Redis container from py-playchoo-api through the playchoo_redis_network network.

Docker

# Development
docker-compose -f docker-compose.dev.yml up

# Production
docker-compose up

Session Format

Sessions stored in Redis under key session:<sessionId>:

{
  "sub": "user-uuid-from-swissoid",
  "email": "user@example.com",
  "iat": 1234567890,
  "exp": 1234575090
}

Integration

Python API (py-playchoo-api)

The Python API reads sessions from the same Redis instance:

# Retrieve session from cookie
session_id = request.cookies.get('playchoo_session')
session_data = redis_client.get(f'session:{session_id}')
user_uuid = json.loads(session_data)['sub']

Frontend (playchoo-nextjs)

Uses swissoid-front React provider:

import { SwissOIDAuthProvider } from 'swissoid-front';

<SwissOIDAuthProvider baseUrl="https://auth.playchoo.com">
  <App />
</SwissOIDAuthProvider>

Related Documentation

• swissoid-back README - OIDC backend integration
• swissoid-front README - React frontend helpers
• Playchoo API README - Session lookup implementation