Stirling PDF

Self-hosted PDF-Toolbox, erreichbar unter pdf.nettailor.net.

• Quelle: github.com/Stirling-Tools/Stirling-PDF
• Live-Instanz: pdf.nettailor.net

Auth-Konzept

Internes Login deaktiviert (SECURITY_ENABLELOGIN: "false"), Zugriffsschutz komplett über Authentik Forward Auth:

• Authentik: Proxy Provider (“Forward auth, single application”), External Host https://pdf.nettailor.net, Application dem Embedded Outpost zugewiesen (ohne das → 404 am Auth-Endpoint)
• NPM Proxy Host → Advanced: authentik-Nginx-Snippet (location /outpost.goauthentik.io + auth_request) sowie client_max_body_size 100M; für größere PDFs
• Zugriffssteuerung über Policy-Bindings an der Authentik-Application; in Stirling selbst gibt es keine Benutzer (alle arbeiten als anonymer Standard-User)

Volumes: Nur /configs (settings.yml, interne DB, Auto-Backups). /usr/share/tessdata, /pipeline, /logs, /customFiles bewusst weggelassen – nur für OCR-Zusatzsprachen, Pipeline-Automation, Log-Persistenz bzw. Branding nötig.

Konfiguration: Ohne Login keine Admin-UI – Einstellungen laufen über Env-Variablen im Compose oder direkt in /configs/settings.yml.

🔧 Lessons Learned: OIDC-SSO ist Bezahlfeature – Forward Auth als Lösung

Datum: Juli 2026

Versuch, Stirling PDF nativ per OIDC an Authentik anzubinden. Der komplette OAuth-Flow ließ sich zum Laufen bringen, scheiterte am Ende aber an der Lizenz – der Weg dahin enthielt drei lehrreiche Stolpersteine:

1. Redirect URI Error (Authentik): Stirling baut die Callback-URL aus SECURITY_OAUTH2_PROVIDER → /login/oauth2/code/<Provider-Name>. Der Wert muss exakt (case-sensitive) als Redirect URI im Authentik-Provider stehen. Außerdem Tippfehler in den Scopes gehabt: openid.profile,email statt openid,profile,email – Punkt statt Komma.
2. “OAuth login failed - no token received”: Ursache war ein 404 auf dem Issuer, nicht (wie zuerst vermutet) Hairpin-NAT. Der Issuer muss den Application-Slug aus Authentik enthalten: https://authn.nettailor.net/application/o/stirling-pdf/. Der Browser-Flow funktioniert auch mit falschem Issuer, weil /application/o/authorize/ slug-unabhängig ist – erst der server-seitige Token/JWKS-Abruf schlägt fehl. Debugging: docker exec stirling-pdf curl -s https://authn.../application/o/<slug>/.well-known/openid-configuration (Hairpin-Problem gab es hier nicht: Domain löst containerintern direkt auf den NPM im Docker-Netz auf).
3. Lizenz-Mauer: Seit Stirling v2 ist OAuth2/OIDC-SSO ein Server-Tier-Bezahlfeature. Log: OAuth login blocked ... no paid license and not grandfathered. Auch manuelles Vorab-Anlegen des Users umgeht das nicht (Meldung wechselt nur auf “blocked for existing user”).

Lösung: Umstieg auf Authentik Forward Auth via NPM (siehe Abschnitt oben) – kein Lizenz-Thema, Authentik-Setup (Application) konnte weiterverwendet werden, nur Provider-Typ von OAuth2 auf Proxy Provider getauscht.

Zusätzliche Falle: enableLogin war in der persistierten /configs/settings.yml noch true und überschrieb die Absicht – Stirling schreibt Settings ins Config-Volume, Env-Änderung allein reicht nicht zwingend. Nach Login-Deaktivierung erschien sonst trotz erfolgreicher Authentik-Anmeldung die Stirling-Login-Maske.

Merke: Bei Self-Hosted-Tools mit “Enterprise”-Tiers vor dem OIDC-Debugging prüfen, ob SSO überhaupt im Free-Tier enthalten ist. Forward Auth vor dem Dienst ist für Single-User/Haushalts-Setups meist die robustere und wartungsärmere Lösung.