221 lines
6.9 KiB
Markdown
221 lines
6.9 KiB
Markdown
# API Authentication Guide
|
||
|
||
## Übersicht
|
||
|
||
Die API verwendet **zwei verschiedene Authentifizierungs-Mechanismen** für unterschiedliche Zugriffslevel:
|
||
|
||
### 1. Admin-Routes (Session + CSRF)
|
||
- **Zweck**: Geschützte Admin-Funktionen (Deletion Log, Cleanup, Moderation, Statistics)
|
||
- **Methode**: HTTP Session (Cookie) + CSRF-Token
|
||
- **Konfiguration**: `.env` → `ADMIN_SESSION_SECRET` (+ Admin-Benutzer in DB)
|
||
|
||
### 2. Management-Routes (UUID Token)
|
||
- **Zweck**: Self-Service Portal für Gruppen-Verwaltung
|
||
- **Methode**: UUID v4 Token in URL-Path
|
||
- **Quelle**: Automatisch generiert beim Upload, gespeichert in DB
|
||
|
||
---
|
||
|
||
## 1. Admin Authentication
|
||
|
||
### Setup
|
||
|
||
1. **Session Secret setzen**:
|
||
```env
|
||
ADMIN_SESSION_SECRET=$(openssl rand -hex 32)
|
||
```
|
||
> ℹ️ Standardmäßig setzt der Server in Production HTTPS-Only Cookies (`Secure`). Falls deine Installation **ohne HTTPS** hinter einem internen Netzwerk läuft, kannst du das Verhalten über `ADMIN_SESSION_COOKIE_SECURE=false` explizit deaktivieren. Verwende dies nur in vertrauenswürdigen Umgebungen und setze den Wert vorzugsweise per lokaler Compose-Override-Datei oder geheimen ENV-Variablen, damit das Repo weiterhin den sicheren Default `true` behält.
|
||
2. **Backend starten** – Migration legt Tabelle `admin_users` an.
|
||
3. **Setup-Status prüfen**:
|
||
```bash
|
||
curl -c cookies.txt http://localhost:5000/auth/setup/status
|
||
```
|
||
4. **Initialen Admin anlegen** (nur wenn `needsSetup=true`):
|
||
```bash
|
||
curl -X POST -H "Content-Type: application/json" \
|
||
-c cookies.txt -b cookies.txt \
|
||
-d '{"username":"admin","password":"SuperSicher123!"}' \
|
||
http://localhost:5000/auth/setup/initial-admin
|
||
```
|
||
5. **Login für weitere Sessions**:
|
||
```bash
|
||
curl -X POST -H "Content-Type: application/json" \
|
||
-c cookies.txt -b cookies.txt \
|
||
-d '{"username":"admin","password":"SuperSicher123!"}' \
|
||
http://localhost:5000/auth/login
|
||
```
|
||
6. **CSRF Token abrufen** (für mutierende Requests):
|
||
```bash
|
||
curl -b cookies.txt http://localhost:5000/auth/csrf-token
|
||
```
|
||
|
||
### Verwendung
|
||
|
||
Alle `/api/admin/*`- und `/api/system/*`-Routen setzen voraus:
|
||
|
||
1. Browser sendet automatisch das Session-Cookie (`sid`).
|
||
2. Für POST/PUT/PATCH/DELETE muss der Header `X-CSRF-Token` gesetzt werden.
|
||
|
||
Beispiel:
|
||
|
||
```bash
|
||
CSRF=$(curl -sb cookies.txt http://localhost:5000/auth/csrf-token | jq -r '.csrfToken')
|
||
curl -X PATCH \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-CSRF-Token: $CSRF" \
|
||
-b cookies.txt \
|
||
-d '{"approved":true}' \
|
||
http://localhost:5000/api/admin/groups/abc123/approve
|
||
```
|
||
|
||
### Geschützte Endpoints (Auszug)
|
||
|
||
| Endpoint | Method | Beschreibung |
|
||
|----------|--------|--------------|
|
||
| `/api/admin/deletion-log` | GET | Deletion Log Einträge |
|
||
| `/api/admin/deletion-log/csv` | GET | Deletion Log als CSV |
|
||
| `/api/admin/cleanup/run` | POST | Cleanup manuell starten |
|
||
| `/api/admin/cleanup/status` | GET | Cleanup Status |
|
||
| `/api/admin/rate-limiter/stats` | GET | Rate-Limiter Statistiken |
|
||
| `/api/admin/groups` | GET | Alle Gruppen (Moderation) |
|
||
| `/api/admin/groups/:id/approve` | PATCH | Gruppe freigeben |
|
||
| `/api/admin/groups/:id` | DELETE | Gruppe löschen |
|
||
| `/api/system/migration/*` | POST | Migrationswerkzeuge |
|
||
|
||
### Error Codes
|
||
|
||
| Status | Bedeutung |
|
||
|--------|-----------|
|
||
| `401` | Session fehlt oder ist abgelaufen |
|
||
| `403` | CSRF ungültig oder Benutzer hat keine Admin-Rolle |
|
||
| `419` | (optional) Session wurde invalidiert |
|
||
|
||
---
|
||
|
||
## 2. Management Authentication
|
||
|
||
### Setup
|
||
|
||
**Kein Setup nötig!** Token werden automatisch generiert.
|
||
|
||
### Funktionsweise
|
||
|
||
1. **Bei Upload** wird automatisch ein UUID v4 Token generiert
|
||
2. **Token wird gespeichert** in DB (Spalte: `management_token`)
|
||
3. **Token wird zurückgegeben** in der Upload-Response
|
||
4. **Nutzer erhält Link** wie: `https://example.com/manage/{token}`
|
||
|
||
### Verwendung
|
||
|
||
Token wird **im URL-Path** übergeben (nicht im Header):
|
||
|
||
```bash
|
||
# Token validieren und Daten laden
|
||
GET /api/manage/550e8400-e29b-41d4-a716-446655440000
|
||
|
||
# Bilder hochladen
|
||
POST /api/manage/550e8400-e29b-41d4-a716-446655440000/images
|
||
|
||
# Gruppe löschen
|
||
DELETE /api/manage/550e8400-e29b-41d4-a716-446655440000
|
||
```
|
||
|
||
### Geschützte Endpoints
|
||
|
||
| Endpoint | Method | Beschreibung |
|
||
|----------|--------|--------------|
|
||
| `/api/manage/:token` | GET | Gruppen-Daten laden |
|
||
| `/api/manage/:token/consents` | PUT | Social Media Consents |
|
||
| `/api/manage/:token/metadata` | PUT | Metadaten bearbeiten |
|
||
| `/api/manage/:token/images` | POST | Bilder hinzufügen |
|
||
| `/api/manage/:token/images/:imageId` | DELETE | Bild löschen |
|
||
| `/api/manage/:token` | DELETE | Gruppe löschen |
|
||
|
||
### Sicherheits-Features
|
||
|
||
- **Token-Format Validierung**: Nur gültige UUID v4 Tokens
|
||
- **Rate Limiting**: Schutz vor Brute-Force
|
||
- **Audit Logging**: Alle Aktionen werden geloggt
|
||
- **DB-Check**: Token muss in DB existieren
|
||
|
||
### Error Codes
|
||
|
||
| Status | Bedeutung |
|
||
|--------|-----------|
|
||
| `404` | Token nicht gefunden oder Gruppe gelöscht |
|
||
| `429` | Rate Limit überschritten |
|
||
|
||
---
|
||
|
||
## Testing
|
||
|
||
### Unit Tests
|
||
|
||
```bash
|
||
npm test -- tests/unit/auth.test.js
|
||
```
|
||
|
||
### Integration Tests
|
||
|
||
```bash
|
||
# Admin Auth testen
|
||
npm test -- tests/api/admin-auth.test.js
|
||
|
||
# Alle API Tests
|
||
npm test
|
||
```
|
||
|
||
### Manuelles Testen
|
||
|
||
1. **Login**:
|
||
```bash
|
||
curl -c cookies.txt -X POST -H "Content-Type: application/json" \
|
||
-d '{"username":"admin","password":"Secret123"}' \
|
||
http://localhost:5000/auth/login
|
||
```
|
||
2. **CSRF holen**:
|
||
```bash
|
||
CSRF=$(curl -sb cookies.txt http://localhost:5000/auth/csrf-token | jq -r '.csrfToken')
|
||
```
|
||
3. **Admin-Route aufrufen**:
|
||
```bash
|
||
curl -b cookies.txt -H "X-CSRF-Token: $CSRF" http://localhost:5000/api/admin/deletion-log
|
||
# → 200 OK
|
||
```
|
||
4. **Ohne Session** (z. B. Cookies löschen) → Request liefert `403 SESSION_REQUIRED`.
|
||
|
||
---
|
||
|
||
## Production Checklist
|
||
|
||
- [ ] `ADMIN_SESSION_SECRET` sicher generieren (>= 32 Bytes random)
|
||
- [ ] `.env` nicht in Git committen (bereits in `.gitignore`)
|
||
- [ ] HTTPS verwenden (TLS/SSL) damit Cookies `Secure` gesetzt werden können (falls nicht möglich: `ADMIN_SESSION_COOKIE_SECURE=false` setzen – nur in vertrauenswürdigen Netzen)
|
||
- [ ] Session-Store auf persistentem Volume ablegen
|
||
- [ ] Rate Limiting & Audit Logs überwachen
|
||
- [ ] Admin-Benutzerverwaltung (On-/Offboarding) dokumentieren
|
||
|
||
---
|
||
|
||
## Sicherheits-Hinweise
|
||
|
||
### Session-Secret Rotation
|
||
|
||
1. Wartungsfenster planen (alle Sessions werden invalidiert)
|
||
2. Neuen `ADMIN_SESSION_SECRET` generieren
|
||
3. `.env` aktualisieren und Backend neu starten
|
||
|
||
### Management-Token
|
||
|
||
- Token sind **permanent gültig** bis Gruppe gelöscht wird
|
||
- Bei Verdacht auf Leak: Gruppe löschen (löscht auch Token)
|
||
- Token-Format (UUID v4) macht Brute-Force unpraktisch
|
||
|
||
### Best Practices
|
||
|
||
- Keine Admin-Secrets im Frontend oder in Repos committen
|
||
- Admin-Session-Cookies nur über HTTPS ausliefern
|
||
- Rate-Limiting für beide Auth-Typen aktiv halten
|
||
- Audit-Logs regelmäßig auf Anomalien prüfen
|
||
- Session-Store-Backups schützen (enthalten Benutzer-IDs)
|