Benjamin Weinlich
88c541c9ed
Adds the Architecture Decision Records that were written during the Forgejo deployment (M7.1) as part of moving docs from the iCloud folder into this versioned repository. Includes: - ADR-0001: Forgejo vs Gitea (non-profit stewardship) - ADR-0002: ai-apps placement (no separate VM) - ADR-0003: Native OIDC, not ForwardAuth - ADR-0004: Subdomain code.sdda.eu - ADR-0005: Volume mount on /data (lesson learned) - ADR-0006: Silent SSO via OAuth2 launch URL (lesson learned) Plus a docs/adr/README.md that explains the ADR format, lists the current ADRs, and provides a template for future entries. Refs OP#1118
48 lines
3.6 KiB
Markdown
48 lines
3.6 KiB
Markdown
# ADR-0003: Natives OIDC statt Authentik ForwardAuth
|
|
|
|
**Status:** Accepted
|
|
**Datum:** 2026-04-11
|
|
**Entscheider:** Benjamin Weinlich
|
|
**Phase:** M7.1 — Forgejo Deployment
|
|
|
|
## Kontext
|
|
Authentik bietet zwei Integrations-Patterns:
|
|
|
|
1. **ForwardAuth / Proxy-Provider:** Der Authentik Embedded Outpost macht Auth vor der App. Traefik leitet Requests zuerst an den Outpost, der User-Claims als HTTP-Header injectet. Die App weiß nichts von OIDC, sieht nur "authenticated" Requests. Unsere bestehenden Apps (n8n, locosoft-hilfe-system) nutzen dieses Pattern.
|
|
|
|
2. **Nativer OIDC Client:** Die App spricht selbst OIDC mit Authentik. Sie macht den Authorization-Code-Flow, holt Tokens, parsed id_token und Userinfo. Kein Outpost als Middleware.
|
|
|
|
Für Forgejo müssen wir wählen.
|
|
|
|
## Entscheidung
|
|
**Nativer OIDC Client** in Forgejo. Forgejo macht den OAuth2-Handshake direkt mit Authentik.
|
|
|
|
## Begründung
|
|
|
|
### Pro natives OIDC
|
|
- **Forgejo ist ein echter OIDC-Client**. Es unterstützt OAuth2/OIDC als First-Class-Feature mit vollem Flow, Token-Exchange, Userinfo-Retrieval, Auto-Registration, Account-Linking via Email.
|
|
- **User-Identität kommt voll an:** Forgejo weiß wer der User ist (Name, Email, Avatar), kann ihn lokal anlegen und persistieren. Bei ForwardAuth sieht es nur "authenticated" plus Header — was für Gruppen-Zuordnung und persistente User-Records umständlich wäre.
|
|
- **Git-Commits signiert:** Forgejo kann Commits im Namen des Users signieren, was mit ForwardAuth und der Proxy-Layer komplizierter würde.
|
|
- **API-Access via Personal Access Tokens:** Entwickler können in Forgejo persönliche API-Tokens erstellen, ohne die Authentik-Credentials teilen zu müssen. Mit ForwardAuth müssten API-Requests durch den Outpost, was API-Keys-im-Header-Pattern bricht.
|
|
- **OIDC ist Standard:** Sollten wir irgendwann Authentik ersetzen (z.B. durch Zitadel, Keycloak), ist der Umstieg trivial, weil OIDC interoperabel ist. Bei ForwardAuth wäre der Umstieg viel schwerer.
|
|
|
|
### Contra
|
|
- **Zweites Auth-Pattern in Authentik:** Bisher haben alle unsere Apps ForwardAuth genutzt. Jetzt kommt ein echter OIDC-Provider dazu. Mehr Komplexität in Authentik (aber: OIDC ist auch das universale Standard-Pattern, unsere ForwardAuth-Apps sind eigentlich die Ausnahme).
|
|
- **Migration bestehender Apps denkbar:** Mittelfristig könnten n8n und andere auch auf nativen OIDC migriert werden, um die Konsistenz wiederherzustellen. Das ist aber ein eigenes Projekt (siehe M7+).
|
|
|
|
## Konsequenzen
|
|
|
|
### Positiv
|
|
- Forgejo-Login-Seite zeigt einen sauberen "Sign in with authentik" Button.
|
|
- User werden automatisch beim ersten Login angelegt (via `ENABLE_AUTO_REGISTRATION=true`, `ACCOUNT_LINKING=auto`, `USERNAME=email`).
|
|
- Gruppen-Zugangskontrolle via Authentik Policy (nur Mitglieder von `forgejo-users`).
|
|
- Kein Traefik ForwardAuth Middleware nötig — Forgejo Docker-Labels sind simpel.
|
|
|
|
### Zu beachten
|
|
- **Discovery-URL muss public sein.** Der Browser und der Forgejo-Backend-Call zum Token-Endpoint müssen dieselbe Issuer-URL benutzen, sonst scheitert die JWT-Issuer-Validation. Daher `https://welcome.sdda.eu/application/o/forgejo/` überall, nicht die private `10.0.0.7`.
|
|
- **OIDC-Provider-Config liegt in Postgres** (Tabelle `login_source`), nicht in `app.ini`. Muss via `forgejo admin auth add-oauth` CLI gesetzt werden, nicht über ENV-Variablen.
|
|
- **Client Credentials in .env nur als Referenz** — die echte Speicherung ist in der DB nach dem CLI-Call.
|
|
|
|
## Follow-Up-Ideen
|
|
- Eine separate ADR für künftige Authentik-OIDC-Integrationen (OpenProject, Nextcloud, vielleicht Migration n8n/locosoft).
|
|
- `Authentik/howto-oauth2-provider.md` als Template für diese zukünftigen Apps schreiben (Teil M7.1).
|