Benjamin Weinlich
6570e81850
Two Forgejo runbooks plus the Authentik OAuth2 provider guide, mirrored from the iCloud folder into the versioned repo. Runbooks: - forgejo-admin-recovery.md — fallback login when Authentik is down using the local admin-local user (prohibit_login reset via SQL). - forgejo-backup-restore.md — backup format, restore scenarios (full / DB-only / single file), disaster recovery on new host. Guides: - authentik-oauth2-provider.md — reusable template for adding native OIDC integrations in Authentik. First applied for Forgejo, ready to reuse for OpenProject, Nextcloud, Grafana. Includes the important launch-URL gotcha from ADR-0006. Each category folder has a README.md with format conventions and an index of the current documents. Refs OP#1118
96 lines
3.8 KiB
Markdown
96 lines
3.8 KiB
Markdown
# Runbook — Admin-Recovery wenn Authentik down ist
|
|
|
|
**Kontext:** Forgejo nutzt Authentik OIDC als Primär-Auth. Wenn Authentik ausfällt, kommt niemand mehr per Login rein. Für diesen Fall gibt es einen lokalen Fallback-User `admin-local`.
|
|
|
|
## Wann dieses Runbook anwenden
|
|
- `welcome.sdda.eu` gibt 500er / nicht erreichbar
|
|
- OIDC-Callback zu Forgejo bricht ab
|
|
- Authentik-Docker-Container crasht
|
|
- authentik-sso VM ist down
|
|
|
|
## Voraussetzung
|
|
- **SSH-Zugang zu ai-apps** (`ssh ai-apps`)
|
|
- **admin-local Passwort** aus Password-Manager / Vault
|
|
|
|
## Recovery-Schritte
|
|
|
|
### 1. PROHIBIT_LOGIN lösen
|
|
Normalerweise ist `admin-local.prohibit_login = true` gesetzt, damit niemand das Passwort bruteforcen kann. Wir müssen es temporär deaktivieren.
|
|
|
|
```bash
|
|
ssh ai-apps
|
|
docker exec forgejo-db psql -U forgejo -d forgejo \
|
|
-c "UPDATE \"user\" SET prohibit_login = false WHERE lower_name = 'admin-local';"
|
|
```
|
|
|
|
Output:
|
|
```
|
|
UPDATE 1
|
|
```
|
|
|
|
### 2. Einloggen
|
|
Im Browser: https://code.sdda.eu/user/login
|
|
- Username: `admin-local`
|
|
- Passwort: aus Password-Manager
|
|
|
|
Du siehst jetzt das Forgejo Dashboard mit Admin-Rechten.
|
|
|
|
### 3. Was du während des Authentik-Ausfalls machen kannst
|
|
- Repos anlegen / ändern
|
|
- User manuell anlegen (fallback wenn jemand dringend Zugang braucht)
|
|
- System-Settings anpassen
|
|
- Backups prüfen
|
|
|
|
**Achtung:** Andere normale User können sich auch nicht einloggen während Authentik down ist. Das ist bewusst so. Wenn ein User dringend arbeiten muss, können sie:
|
|
- Von dir ein Personal Access Token bekommen (Settings → Applications)
|
|
- git clone via HTTPS mit diesem Token
|
|
|
|
### 4. Authentik wieder hochbringen
|
|
```bash
|
|
ssh authentik-sso
|
|
cd /opt/authentik
|
|
docker compose ps # Was läuft?
|
|
docker compose logs --tail 50 # Warum down?
|
|
docker compose restart # Versuch 1
|
|
# Wenn restart nicht hilft: docker compose up -d --force-recreate
|
|
```
|
|
|
|
Bei Datenbank-Problemen:
|
|
```bash
|
|
docker compose logs authentik-db # DB ok?
|
|
# Im Worst Case: Restore aus Authentik-Backup
|
|
```
|
|
|
|
### 5. Nach der Wiederherstellung: PROHIBIT_LOGIN zurücksetzen
|
|
**WICHTIG:** Sobald Authentik wieder läuft, sofort den Notfall-Fallback wieder sperren:
|
|
|
|
```bash
|
|
ssh ai-apps
|
|
docker exec forgejo-db psql -U forgejo -d forgejo \
|
|
-c "UPDATE \"user\" SET prohibit_login = true WHERE lower_name = 'admin-local';"
|
|
```
|
|
|
|
Aus dem Forgejo Admin-UI deine bw-Session ausloggen, dann via Authentik neu einloggen — sicherstellen dass OIDC wieder funktioniert.
|
|
|
|
## Warum dieses Pattern?
|
|
- **admin-local hat keinen Zugang über Authentik** (nicht in Gruppe `forgejo-users`, und nicht mal ein OIDC-linked User).
|
|
- **admin-local ist per default gesperrt** (`prohibit_login=true`).
|
|
- Zum Aktivieren braucht man DB-Zugang → bedeutet SSH-Zugang zu ai-apps → bedeutet physischen Zugang zu deinem Rechner / SSH-Key.
|
|
- Nach Recovery sofort zurück in den gesperrten Zustand — kein dauerhaftes Bypass.
|
|
|
|
## Was du NIE machen solltest
|
|
- **admin-local Passwort aus dem Password-Manager entfernen.** Das ist deine einzige Notfall-Tür.
|
|
- **admin-local Passwort in Klartext irgendwo committen.** Das ist wie GH-Secret-in-Public-Repo, nur schlimmer.
|
|
- **PROHIBIT_LOGIN dauerhaft auf false lassen nach Recovery.** Das bricht das Sicherheitsprinzip.
|
|
|
|
## Alternative für sehr lange Authentik-Ausfälle
|
|
Wenn Authentik auf Dauer nicht mehr funktioniert (z.B. Lizenz-Issue, Migration nötig):
|
|
1. admin-local temporär entsperren
|
|
2. OIDC-Auth-Source in Forgejo deaktivieren: `docker exec -u git forgejo sh -c 'cd / && forgejo admin auth update-oauth --id 1 --not-enabled'`
|
|
3. Lokale User bestehen bleibt (bw kann admin-local-Passwort bekommen oder eigenes lokales Passwort setzen)
|
|
4. Neuer Auth-Provider später einrichten
|
|
5. Doku in neue ADR schreiben
|
|
|
|
## Related
|
|
- `Agent.md` — Stack-Overview
|
|
- `../Authentik/howto-oauth2-provider.md` — Wie OIDC-Provider neu aufgesetzt wird
|