# 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

```bash
npm install
```

### 2. Configure Environment

Copy `.env` and update with your values:

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

### 3. Prepare the shared Redis instance

```bash
# 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

```bash
npm run dev
```

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

### 5. Test the Endpoints

**Health Check**:
```bash
curl http://localhost:3700/healthz
```

**Auth Status** (should return unauthenticated):
```bash
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

```bash
npm run build:prod
```

### 2. Update Production Environment

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

### 3. Deploy with Docker

```bash
docker-compose up -d
```

## Verify Integration

### Check Session Storage

After logging in, check Redis for your session:

```bash
# 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:
```json
{
  "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](../swissoid-back/README.md)
- [Integration Summary](../SWISSOID_INTEGRATION_SUMMARY.md)
- SwissOID documentation