Richter-und-Zech/electric-horses-infra
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
electric-horses-infra/docs/adr/0003-native-oidc-not-forwardauth.md
Benjamin Weinlich 88c541c9ed docs(adr): mirror 6 ADRs from M7.1 into repo 
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
2026-04-11 22:26:05 +02:00

3.6 KiB
Raw Blame History

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).