You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
123 lines
3.3 KiB
Markdown
123 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```env
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# Development
|
|
docker-compose -f docker-compose.dev.yml up
|
|
|
|
# Production
|
|
docker-compose up
|
|
```
|
|
|
|
## Session Format
|
|
|
|
Sessions stored in Redis under key `session:<sessionId>`:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```tsx
|
|
import { SwissOIDAuthProvider } from 'swissoid-front';
|
|
|
|
<SwissOIDAuthProvider baseUrl="https://auth.playchoo.com">
|
|
<App />
|
|
</SwissOIDAuthProvider>
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [`swissoid-back` README](../swissoid-back/README.md) - OIDC backend integration
|
|
- [`swissoid-front` README](../swissoid-front/README.md) - React frontend helpers
|
|
- [Playchoo API README](../py-playchoo-api/README.md) - Session lookup implementation
|