Paperless-ngx Multi-Faktor-Authentifizierung MFA aktivieren

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.

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.

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

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.

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

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.

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.

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.

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

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!

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

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.

Eine einfache Lösung die Sicherheitslücke zu schließen, ist den Pfad /admin/ in deinen Web-Server Einstellungen zu 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.

Ein weiterer Wermutstropfen ist, wie ich finde, dass sich theoretisch jeder Besucher auf deiner Login-Seite registrieren kann. 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.

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.

Ich biete für meine Kunden eine umfassende Absicherung des Servers an. Das beinhaltet unter anderem die Verwendung von

• SSH Keys
• DDOS- und Brute-Force-Schutz
• IP Blocking
• verschlüsselte Verbindung über HTTPS / TLS Zertifikat
• Reverse Proxy
• Firewall
• Backup System
• und optionalen VPN Zugang.

Kontaktiere mich gerne bei Interesse unter hello@digitizerspace.com.

🛠️ Paperless-ngx IT-Support 🛠️

Du benötigst Unterstützung bei der Installation oder Konfiguration von Paperless-ngx? Ich helfe dir gerne weiter! Schreib mir einfach eine Mail an: hello@digitizerspace.com