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.
181 lines
4.3 KiB
Markdown
181 lines
4.3 KiB
Markdown
# 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
|