Single Sign-On (SSO) einrichten
Du kannst dein Paperless-ngx so konfigurieren, dass sich Nutzer per Single Sign-On (SSO) gegen deinen Identity-Provider anmelden. Paperless-ngx nutzt dafür den Standard OpenID Connect – es funktioniert also mit Authentik, Keycloak, Zitadel, Google Workspace, Microsoft Entra ID und anderen OIDC-fähigen Providern.
- Ein aktives Paperless-ngx-Abonnement bei server.camp
- Eine erreichbare, OIDC-fähige Identity-Provider-Instanz
- Admin-Zugang zu beiden Systemen
Lege bei deinem Identity-Provider eine neue OAuth2/OpenID-Anwendung für Paperless-ngx an. Das genaue Vorgehen unterscheidet sich je nach Provider. Trage dort die folgende Redirect-URI ein:
https://<deine-paperless-domain>/accounts/oidc/sso/login/callback/
Der Pfadbestandteil sso ist fest vorgegeben und unabhängig vom später vergebenen Provider-Namen. Nutzt du eine eigene Domain für Paperless-ngx, hinterlege zusätzlich deren Callback-URL.
Notiere dir abschließend die Client ID, das Client Secret sowie die OpenID-Konfigurations-URL (auch “Discovery-URL” oder “well-known-URL” genannt). Das ist die URL, unter der /.well-known/openid-configuration erreichbar ist, z. B.:
https://dein-authentik.srv.camp/application/o/paperless/.well-known/openid-configuration
Zugang auf Gruppen beschränkenBeschränke beim IdP den Zugriff auf die Anwendung auf eine bestimmte Gruppe (z. B.alle-mitarbeiter). So können sich nur Mitglieder dieser Gruppe über SSO in Paperless-ngx anmelden.
Öffne im Kundenportal die Konfiguration deines Paperless-ngx-Abonnements und trage die folgenden Werte ein:
| Feld | Wert |
|---|---|
| Single Sign-on aktivieren | Angehakt |
| Provider Name | Frei wählbar, z. B. Authentik – erscheint als Beschriftung des Login-Buttons |
| Client ID | Aus deinem IdP kopiert |
| Client Secret | Aus deinem IdP kopiert |
| OpenID Konfigurations-Endpunkt | Discovery-URL aus Schritt 1 |
Speichern und warten, bis die Bereitstellung abgeschlossen ist (ca. 1–2 Minuten). Auf der Login-Seite von Paperless-ngx erscheint danach zusätzlich ein Button zur Anmeldung über deinen Provider.
Die folgenden Felder sind optional. Setze sie nur, wenn du gezielt vom Standardverhalten abweichen möchtest:
| Feld | Standard | Wirkung |
|---|---|---|
| Registrierung zulassen | Nicht angehakt | Erlaubt neuen Nutzern, sich per OpenID Connect selbst zu registrieren. Ohne diese Option können sich nur bereits existierende Konten anmelden. |
| Provider Registrierungsformular nutzen | Nicht angehakt | Überspringt den Paperless-ngx-Registrierungsdialog und übernimmt Name, E-Mail usw. direkt vom Identity-Provider. |
| Gruppen synchronisieren | Nicht angehakt | Fügt Nutzer auf Basis ihrer Gruppenzugehörigkeit im IdP den entsprechenden Paperless-Gruppen hinzu bzw. entfernt sie. Die Gruppen müssen in Paperless-ngx vorab existieren. |
| Standard Gruppen | – | Komma-separierte Liste von Gruppen, denen neue Nutzer automatisch zugeordnet werden. Die Gruppen müssen vorab manuell angelegt werden. |
| Logout Redirect-URL | – | URL, auf die nach dem Logout weitergeleitet wird (z. B. das Logout-Formular deines Providers). |
- Paperless-ngx im Browser öffnen
- Auf der Login-Seite den Button für deinen Provider anklicken
- Weiterleitung zum IdP, dort anmelden
- Zurück in Paperless-ngx – der Nutzer ist angemeldet
Erst testen, dann umstellenDas klassische Login-Formular bleibt neben dem SSO-Button erhalten. So kommst du bei einer fehlerhaften Konfiguration weiterhin mit deinem lokalen Admin-Konto hinein.
- “redirect_uri mismatch” beim IdP: Prüfe, ob die Redirect-URI exakt hinterlegt ist – inklusive Pfad (
/accounts/oidc/sso/login/callback/) und abschließendem Schrägstrich. - Kein SSO-Button sichtbar: Ist “Single Sign-on aktivieren” angehakt und die Bereitstellung im Portal abgeschlossen?
- Anmeldung schlägt mit “Konto existiert nicht” fehl: Aktiviere “Registrierung zulassen”, damit sich neue Nutzer per SSO anmelden dürfen, oder lege das Konto vorab in Paperless-ngx an.
Bei weiteren Fragen erreichst du unseren Support über das Kundenportal.