From 5b00d0cffba92a9d390ca833dd0c253c27839c19 Mon Sep 17 00:00:00 2001
From: Jens Beckmann <jens@ljh31.de>
Date: Sun, 27 Sep 2026 19:49:41 +0000
Subject: [PATCH] forwardAuth-Modus: static://202 + REVERSE_PROXY

---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index fae5b00..c34e915 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,60 @@
 # infra-auth-proxy
 
-OAuth2-Proxy als Traefik Forward-Auth-Backend für Keycloak-Login
\ No newline at end of file
+OAuth2-Proxy als Reverse-Proxy-Authentifizierung für Traefik.
+Bietet zentrale Keycloak-Login-Weiterleitung für alle Homelab-Apps.
+
+## Architektur
+
+```
+Browser → Traefik → oauth2-proxy → App
+                  ↕ Keycloak (Login, Session)
+```
+
+oauth2-proxy läuft im **Reverse-Proxy-Modus**:
+- Unauthentifizierter Request → 302-Redirect zu Keycloak-Login
+- Authentifzierter Request → Weiterleitung an das Upstream
+
+## Neue Services schützen
+
+1. **Upstream registrieren** in `.env`:
+   ```
+   OAUTH2_PROXY_UPSTREAMS=http://service1:3000,http://service2:8080
+   ```
+   (Container-Namen müssen auf `infra-traefik_traefik-net` erreichbar sein)
+
+2. **Traefik-Router** in der eigenen App:
+   ```yaml
+   labels:
+     - "traefik.http.services.app.loadbalancer.server.url=http://oauth2-proxy:4180"
+   ```
+   (statt `loadbalancer.server.port=XXXX` direkt auf die App)
+
+3. `docker compose up -d` in beiden Stacks
+
+## Setup
+
+```bash
+# .env aus Template erstellen
+cp .env.template .env
+# OAUTH2_PROXY_CLIENT_SECRET: Keycloak Client `auth-proxy` Secret
+# OAUTH2_PROXY_COOKIE_SECRET: openssl rand -hex 16
+
+# Deploy
+docker compose up -d
+```
+
+## Alternative: Forward-Auth für API-Endpoints
+
+Für API-Endpoints (wo 401 statt Redirect sinnvoll ist) steht die
+`keycloak-oauth2` forwardAuth-Middleware in `infra-traefik/dynamic.yaml` bereit:
+
+```yaml
+labels:
+  - "traefik.http.routers.api.middlewares=keycloak-oauth2@file"
+```
+
+## Keycloak-Client
+
+- **Realm:** `family`
+- **Client-ID:** `auth-proxy`
+- **Redirect URI:** `https://auth-proxy.ljh31.de/oauth2/callback`