Get exclusive business insights on tech and automation delivered weekly — Join our free newsletter!

Paperless-ngx Multi-Faktor-Authentifizierung MFA aktivieren

Aktiviere die in Paperless-ngx integrierte Multi-Faktor-Authentifizierung und sichere deinen Zugang ab. Alle Konfigurationen für 2FA im Überblick.

Zuletzt aktualisiert: 17. Okt. 2024

7 min Lesezeit
Portrait von Tobias Wupperfeld

Autor

Tobias Wupperfeld

Tobias ist ein erfahrener Softwareentwickler und der Gründer von PaperlessZone. Seine Leidenschaft für Innovation treibt ihn an, Lösungen zur Effizienzsteigerung zu entwickeln. Er ermöglicht KMUs durch digitale Transformation und Automatisierung in einem kompetitiven Umfeld erfolgreich zu sein.

Themen

Thumbnail: Multi-Faktor-Authentifizierung in Paperless-ngx einrichten

Einleitung

Die Weboberfläche von Paperless-ngx bietet nach der Standard-Installation nur einen Login mit Benutzername und Passwort.

Im Jahr 2024 ist das nicht gerade sicher. Falls jemand dein Passwort herausfindet, ist er im System. Wird nicht passieren, denkst du? Es braucht nur ein Datenleck zu geben. Eine Phishing E-Mail oder ein Virus, der die Tastatureingaben aufnimmt. Oder das Fehlen einer verschlüsselten Verbindung über HTTP. Gerade wenn es um sensible Dokumente geht, ist ein zusätzlicher Schutz unentbehrlich.

Paperless-ngx unterstützt seit dem Release 2.5.0 eine Integration einer Multi-Faktor-Authentifizierung über diverse Anbieter.

Multi-Faktor oder Zwei-Faktor bedeutet, dass du zusätzlich zu deiner Passworteingabe den Login über eine weitere Methode bestätigen musst. Z. B. durch Eingabe eines TOTP Codes, den du per E-Mail, SMS oder über eine Smartphone-App abrufst. Um das zu umgehen, bräuchte ein Angreifer gleichzeitig Zugang zu beiden Methoden, was deutlich schwieriger ist.

Schritt 1: Anbieter auswählen

Die Multi-Faktor-Authentifizierung erfolgt über einen externen Anbieter. Paperless-ngx nutzt ein Django Backend und unterstützt alle Django Allauth Anbieter. Du kannst hier eine Liste aller Anbieter sehen und dir einen oder mehrere Anbieter aussuchen.

Falls du eine Anwendung für die Authentifizierung selbst hosten möchtest, bietet sich z. B. die openid-connect (OIDC) Schnittstelle an. OIDC kannst du mit Authelia oder Keycloak verbinden - zwei beliebte Open-Source-Software Tools. Die Einrichtung erfordert allerdings deutlich mehr technisches Wissen. Wenn dich ein Tutorial dazu interessiert, lass es mich in den Kommentaren wissen.

Die meisten Drittanbieter kannst du sehr einfach einrichten. Ich zeige dir hier exemplarisch die Einrichtung mit GitHub, die kostenlos ist. Die Einrichtung mit anderen Anbietern ist ähnlich.

Das kann dir bei der Auswahl des richtigen Providers zusätzlich helfen: Finde heraus, bei welchen Anbietern ein Großteil deiner Mitarbeiter bereits einen Account hat.

Schritt 2: App registrieren

Zunächst registrierst du deine Paperless App bei einem der Anbieter. Dann erhältst du eine Client-ID und einen Sicherheits-Schlüssel (Secret) vom Anbieter.

Für die Registrierung mit GitHub gehst du dazu auf diese Seite und füllst alle Pflichtfelder aus. Du kannst einen beliebigen Namen für deine App setzen.

Als Homepage URL setzt du die URL, unter der deine Paperless Instanz erreichbar ist.

Zuletzt definierst du die Callback URL, auf die GitHub bei erfolgreichem Login weiterleitet. Dazu fügst du diesen Abschnitt an das Ende deiner Homepage URL hinzu /accounts/github/login/callback/.

register paperless app in github

Nachdem du das Formular abgeschickt hast, kannst du dir ein Client Secret generieren. Für den nächsten Schritt brauchst du das Client Secret und die Client-ID.

Copy client id and secret key for your app

Schritt 3: Environment Variablen hinzufügen

Öffne das Verzeichnis, wo du Paperless-ngx installiert hast und die Docker Compose Konfigurationen liegen. Öffne die Datei docker-compose.env. Ich verbinde mich via SSH mit meinem Linux Server und öffne die Datei mit dem Texteditor nano:

sudo nano docker-compose.env

An das Ende der Datei fügst du zwei Variablen ein:

PAPERLESS_APPS: allauth.socialaccount.providers.github
PAPERLESS_SOCIALACCOUNT_PROVIDERS: {"github": {"APPS": [{"provider_id": "github","name": "Github","client_id": "<CLIENT_ID>","secret": "<CLIENT_SECRET>"}]}

Ersetze die Platzhalter <CLIENT_ID> und <CLIENT_SECRET> mit deinen Keys.

Speicher die Datei ab und schließe den Texteditor. Ich verwende dazu die Befehle STRG+X gefolgt von Y und ENTER.

Um die Einstellungen zu speichern, musst du die Docker Container neu starten. Führe folgenden Befehl aus:

docker compose down && docker compose up -d

Nach etwa einer Minute sollte deine Paperless Instanz wieder erreichbar sein.

Schritt 4: Anbieter in Paperless App aktivieren

Wenn du jetzt zu deiner Paperless Instanz navigierst, siehst du zwei Login-Möglichkeiten: Login mit Github und den regulären Login mit Benutzername und Passwort.

Zwei Login Optionen in Paperless

Logge dich zunächst mit deinen regulären Zugangsdaten ein

Logge dich wie bisher mit deinen regulären Zugangsdaten in dein Admin-Konto ein. Rufe dein Profil auf. Du siehst jetzt einen Button, mit dem du dein Konto mit Github verbinden kannst.

github mit paperless-ngx verbinden über profil

Verbinde Paperless mit GitHub über den Button in deinem Profil

Klicke auf den Button und verbinde dein Konto. Logge dich in Paperless und deinem Github Konto aus und teste, ob du dich mit Github einloggen kannst. Das sollte problemlos funktionieren.

Damit die Multi-Faktor-Authentifizierung funktioniert, musst du diese deinem Github Konto hinzufügen. Solange deine Github Sitzung aktiv ist, wirst du in deiner Paperless Instanz eingeloggt bleiben.

Schritt 5: Regulären Login deaktivieren

Öffne wieder die docker-compose.env Datei. Füge eine weitere Variable an das Ende der Datei ein:

PAPERLESS_DISABLE_REGULAR_LOGIN=true

Speicher und schließ die Datei und starte die Docker Container neu. Wenn Paperless wieder online ist, sollte der reguläre Login verschwunden sein.

Melde dich in Paperless mit GitHub an

Einige wichtige Limitationen

Es gibt zwei Einschränkungen, mit denen du aktuell leben musst, wenn du die Paperless MFA Integration nutzen möchtest. Vielleicht wird es in zukünftigen Updates gepatcht.

Admin Panel Sicherheitslücke

Es gibt derzeit eine Sicherheitslücke, die unsere gesamte Vorarbeit zunichtemacht. Das ist das Django Admin Panel. Das Django Admin Panel kannst du über den URL-Pfad /admin/ aufrufen. https://paperless.domain.com/admin/

In das Admin Panel kannst du dich weiterhin mit deinen regulären Zugangsdaten einloggen!

django admin panel login in paperless

Login in das Admin Panel ist mit regulären Zugangsdaten möglich

Django Admin Panel in Paperless

Admin Panel mit dem Link auf das Dashboard

Sobald du eingeloggt bist, kannst du auf dein Paperless Dashboard navigieren und hast Zugang zu allen deinen Dokumenten. Das heißt: Du kannst damit die Multi-Faktor-Authentifizierung umgehen, was nicht Sinn der Sache ist.

Update: seit Version 2.8 kannst du das Admin Panel deaktivieren, indem du die Berechtigung in deinen Benutzereinstellungen entfernst:

Admin Panel in Benutzereinstellungen deaktivieren

Du kannst das Admin Panel in den Benutzereinstellungen deaktivieren

Alternativ kannst du den Pfad /admin/ in deinen Web-Server Einstellungen blocken. Wo du die Einstellungen genau vornehmen musst, hängt von dem Web-Server ab, den du verwendest und wo dieser auf deinem System installiert ist.

Wenn du wie ich Nginx als Reverse Proxy verwendest, hast du wahrscheinlich das Verzeichnis /etc/nginx/sites-available. Hier liegt die Konfiguration für meine Domain, unter der meine Paperless Instanz läuft.

Gehe in das Verzeichnis:

cd /etc/nginx/available

Öffne die Konfiguration:

sudo nano paperless.domain.com

Füge folgenden Code in deinen Server Block ein:

location /admin/ {
    return 302 /;
}

Was macht der Code? Sobald ein Benutzer den Pfad zum Admin Panel aufruft, wird er auf den Heimpfad / weitergeleitet. Dabei wird ein HTTP Status Code 302 (temporäre Weiterleitung) geworfen.

Speicher und schließ die Datei und teste auf Syntax Fehler mit:

sudo nginx -t

Ist alles ok, starte Nginx neu:

sudo systemctl restart nginx

Damit ist die Sicherheitslücke geschlossen.

Der Wermutstropfen: Du kannst das Django Admin Panel nicht mehr verwenden. Auch dann nicht, wenn du eingeloggt bist.

Registrierung zusätzlicher Benutzer

Ein neuer Benutzer kann sich einfach über die Login-Seite mit seinem GitHub Konto für deine App registrieren. Der Benutzer erscheint dann in deinem Konto unter der Benutzeransicht.

Theoretisch kann sich jeder Besucher auf deiner Login-Seite registrieren. Aber keine Sorge: Nach der Registrierung hat der Benutzer keinerlei Berechtigungen oder Zugang zu deinen Daten.

Du musst in der Benutzeransicht den Benutzer bearbeiten und ihm Berechtigungen zuweisen. Falls der Benutzer nicht autorisiert sein sollte, kannst du ihn einfach löschen.

Wenn du die Registrierung neuer Benutzer über deine Login-Seite deaktivieren möchtest, füg einfach die Variable PAPERLESS_SOCIALACCOUNT_ALLOW_SIGNUPS=False zu deiner Konfiguration hinzu und starte deine Dockercontainer neu.

Fazit

Die Integration einer Multi-Faktor-Authentifizierung in Paperless ist ein wichtiger Schritt, um deine Instanz sicherer vor Angreifern zu machen. Die Einbindung der Django Allauth Anbieter ist simpel, geht aber mit ein paar Limitationen einher.

Es gibt wesentlich mehr Möglichkeiten deine Paperless Instanz abzusichern. Das meiste ist ein generelles Server-Thema und hat per se nichts mit der Paperless App zu tun. Du könntest z. B. eine Multi-Faktor-Authentifizierung über Authelia mit deinem Reverse Proxy verbinden. Bei jeder eingehenden Anfrage wird eine Authentifizierungs-Anfrage gesendet. Die Antwort weist den Reverse Proxy an, die eingehende Anfrage entweder durchzulassen oder zu blockieren. Erst bei erfolgreicher Authentifizierung wird Paperless geladen.

🛟 Benötigst du professionelle Unterstützung?

Wir helfen dir gerne bei der nahtlosen Integration und Einrichtung von Paperless-ngx, einem spezifischen Auth-Anbieter, und mehr. Wir bieten maßgeschneiderte Lösungen, um deine Geschäftsprozesse zu optimieren und Arbeitsabläufe zu automatisieren.

Kontaktiere uns noch heute, um eine Beratung zu erhalten oder deine spezifischen Anforderungen zu besprechen!

Kontaktiere uns

Kommentare

ARO

2. Mai 2024, 21:03

Hallo Tobias ... vielen Dank für den tollen Beitrag. Hab ich natürlich gleich in meiner paperless-ngx Umgebung umgesetzt. Das "Problem" mit der zusätzlichen Benutzer Registrierung kann man aus meiner Sicht mit "PAPERLESS_SOCIALACCOUNT_ALLOW_SIGNUPS: false" beheben. Viele Grüße! ARO

Tobias Wupperfeld

22. Juli 2024, 10:54

Hallo ARO, danke für den Tipp mit der zusätzlichen Variable!

Martin

24. Mai 2024, 11:04

Kann ein TOTP mit "Google Authenticator" konfiguriert werden? Ich finde dazu keinen Eintrag: https://docs.allauth.org/en/latest/socialaccount/providers/index.html#provider-specifics

Tobias Wupperfeld

22. Juli 2024, 10:56

Hi Martin, wenn du Google einbindest, wirst du bei Anmeldung zum Google Login weitergeleitet und kannst dort TOTP nutzen, sofern du das in deinem Google Account aktiviert hast.

Rüdiger

9. Juni 2024, 20:01

Hallo Tobias, kann mich ARO gerne anschliesssen. Toller Beitrag. Ein Thema zu dem man auch auf Englisch wenig findet. Und es funktionierte auf Anhieb! Würde mich auch über ein paar kurze paperless spezifische Infos zu keycloak freuen, e.g. Werte für PAPERLESS_APPS, PAPERLESS_SOCIALACCOUNT_PROVIDERS Eine kleine Frage für mein Verständnis: an Security meiner paperless Instanz habe ich nichts gewonnen, solange der User seinen Github Account nicht sichert (z.B. passkeys, 2FA) und darauf habe ich keinen Einfluss? Viele Grüße r.

Tobias Wupperfeld

22. Juli 2024, 11:09

Hallo Rüdiger, für keycloak würde ich die Konfiguration probieren wie sie in den [allauth docs](https://docs.allauth.org/en/latest/socialaccount/providers/keycloak.html) steht: PAPERLESS_SOCIALACCOUNT_PROVIDERS = {"openid_connect": {"APPS": [{"provider_id": "keycloak","name": "Keycloak","client_id": "<DEINE_ID>","secret": "<DEIN_SECRET>","settings": {"server_url": "<DEINE_LOGIN_URL>",},}]}} PAPERLESS_APPS: allauth.socialaccount.providers.openid_connect Wenn der Github account unsicher ist, dann gewinnst du nichts an Sicherheit, genau richtig.

erich

24. Aug. 2024, 03:56

Hallo Tobias, ich habe eine Paperless-Instanz mit der von Dir beschriebenen Methode mit 2FA abgesichert. Ich weiss, VPN wäre sicherer. Da ich aber diese Instanz nur während meiner Wohnmobil-Reisen und für die auf diesen Reisen entstehenden Dokumente nutzen werde, geht Bequemlichkeit vor Sicherheit. Mein Hauptinstanz (anderes NAS) ist nur via VPN erreichbar. Dennoch Deine Einschätzung: Würdest Du sagen, dass eine so (2FA via GitHub) abgesicherte Instanz recht gut geschützt ist? Klar, wenn jemand rein will, wird er es schaffen, aber so ganz einfach dürfte es wohl nicht sein. Wie siehst Du das? Beste Grüsse - Erich

Tobias Wupperfeld

31. Aug. 2024, 08:51

Hallo Erich, um über die Webapplikation reinzukommen, müsste dein Github Konto geknackt werden. Ich denke das ist unwahrscheinlich, wenn du es mit 2FA gesichert hast. Ein anderer Weg wäre über deinen Server reinzukommen. Deswegen solltest du den auch ausreichend sichern, z.b. SSH Zugriff über externe Netzwerke deaktivieren oder SSH keys verwenden, etc. Vom Nutzen / Aufwand her macht das dann glaube ich kaum Sinn für einen Hacker. Eine effektivere Methode heutzutage ist z.B. Phishing, wo versucht wird über Fake-Webseiten und andere Tricks die Zugangsdaten abzufragen.

Hinterlasse einen Kommentar

Deine E-Mail Adresse wird nicht veröffentlicht.