playchoo-manager-auth/README.md

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 /auth/status - Returns current authentication status
• POST /auth/logout - Destroys session
• 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

# 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.

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