playchoo-manager-auth/QUICKSTART.md

Quick Start Guide - playchoo-auth

Prerequisites

1. Redis running locally or accessible
2. SwissOID client credentials (client ID + secret)
3. Node.js 20+ installed

Local Development Setup

1. Install Dependencies

npm install

2. Configure Environment

Copy .env and update with your values:

cp .env .env.local
# Edit .env.local with your SwissOID credentials

3. Prepare the shared Redis instance

# Ensure the shared network exists (no-op if it already does)
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)

If you run the Node service directly on your machine, set REDIS_URL to redis://localhost:6379. Inside Docker the compose file rewrites it to redis://redis:6379 automatically.

4. Start the Auth Service

npm run dev

The service will start on http://localhost:3700.

5. Test the Endpoints

Health Check:

curl http://localhost:3700/healthz

Auth Status (should return unauthenticated):

curl http://localhost:3700/auth/status

Login (open in browser):

http://localhost:3700/login

This will redirect to SwissOID, and after login, redirect back to your RP_FRONTEND_URL.

Production Deployment

1. Build the Application

npm run build:prod

2. Update Production Environment

cp .env.prod .env.prod.local
# Edit .env.prod.local with production values

3. Deploy with Docker

docker-compose up -d

Verify Integration

Check Session Storage

After logging in, check Redis for your session:

# Connect to Redis
redis-cli

# List all session keys
KEYS session:*

# View a specific session
GET session:<your-session-id>

You should see JSON like:

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

Test Cookie Setting

Use browser DevTools:

1. Open Network tab
2. Visit http://localhost:3700/login
3. Complete SwissOID flow
4. Check Application → Cookies
5. Verify playchoo_session cookie is set with:
   • Domain: .playchoo.com (or localhost in dev)
   • Secure: true (in production)
   • HttpOnly: true
   • SameSite: None (or Lax)

Troubleshooting

"Session not found" in API

• Verify Redis is running: redis-cli ping
• Check cookie name matches in both services: SESSION_COOKIE_NAME
• Ensure REDIS_URL is the same in auth service and API

SwissOID callback fails

• Verify OIDC_REDIRECT_BASE_URL matches your registered redirect URI
• Check SwissOID client is configured for authorization_code flow
• Ensure SWISSOID_CLIENT_SECRET is correct

Cookie not set

• Check RP_COOKIE_DOMAIN matches your domain structure
• For localhost, use localhost (no leading dot)
• For production, use .playchoo.com (with leading dot)
• Verify CORS_ALLOWED_ORIGIN includes your frontend URL

CORS errors

• Add frontend URL to CORS_ALLOWED_ORIGIN
• Ensure frontend uses credentials: 'include' in fetch
• Check browser console for specific CORS error

Environment Variables Reference

Variable	Description	Example
SWISSOID_CLIENT_ID	SwissOID client identifier	playchoo
SWISSOID_CLIENT_SECRET	SwissOID client secret	<secret>
SESSION_COOKIE_NAME	Name of session cookie	playchoo_session
SESSION_TTL	Session lifetime (seconds)	7200 (2 hours)
REDIS_URL	Redis connection string	redis://redis:6379
RP_FRONTEND_URL	Frontend redirect after login	https://app.playchoo.com
RP_COOKIE_DOMAIN	Cookie domain	.playchoo.com

Next Steps

1. Integrate with py-playchoo-api: See /py-playchoo-api/README.md
2. Update Frontend: Install swissoid-front and configure provider
3. Configure Production Secrets: Use a secrets manager for sensitive values
4. Set up Monitoring: Add alerts for Redis health, auth failures
5. Test End-to-End: Complete login flow from frontend → auth → API

Support

For issues or questions, check:

• swissoid-back README
• Integration Summary
• SwissOID documentation