Behebung des Fehlers „CSRF-Verifizierung fehlgeschlagen“ in Paperless-ngx

Wenn Paperless-ngx anzeigt 403 Verboten: CSRF-Verifizierung fehlgeschlagen Beim Anmelden wurde die Anfrage aufgrund einer Sicherheitsprüfung abgelehnt. Dies tritt häufig nach einer Änderung der Domain, der Aktivierung von HTTPS oder der Konfiguration eines Reverse-Proxys auf, kann aber auch mit Cookies oder einem veralteten Formular zusammenhängen.

Die Lösung besteht darin, die genaue Ursache zu ermitteln, die öffentliche URL zu überprüfen und sicherzustellen, dass die Konfiguration Paperless tatsächlich erreicht. Sie müssen den CSRF-Schutz nicht deaktivieren oder die Dokumentberechtigungen ändern.

Ermitteln Sie die Ursache des CSRF-Fehlers in Paperless-ngx.

Django verwendet Cookies und Tokens sowie Überprüfungen des Ursprungs von Anfragen, um es anderen Websites zu erschweren, Aktionen durch Ausnutzung der Benutzersitzung zu senden.

Prüfen Sie, ob in der Mitteilung ausdrücklich Folgendes erwähnt wird: CSRF-Verifizierung fehlgeschlagenEin 403-Fehler, der von Cloudflare, einer Proxy-Regel oder einem externen Zugriffssystem generiert wird, kann auch eine andere Ursache haben.

Wenn Sie Docker Compose verwenden, reproduzieren Sie den Fehler und überprüfen Sie die Protokolle:

docker compose logs --tail=100 webserver

In den Beispielen, die wir verwendet haben webserver als Dienstnamen. Ersetzen Sie ihn durch den Namen Ihrer Bereitstellung. Suchen Sie nach Verweisen auf django.security.csrf und der Grund für die Ablehnung.

• Ursprungsprüfung fehlgeschlagen: Überprüfen Sie die in der Benachrichtigung angegebene Quelle und die öffentlichen Einstellungen.
• CSRF-Cookie nicht gesetzt: Prüfen Sie, ob der Browser den Cookie empfängt und speichert.
• Token fehlt oder ist falsch: Laden Sie das Formular neu, bevor Sie es absenden.
• Referrer-Prüfung fehlgeschlagen: Überprüfen Sie die Header und greifen Sie über HTTPS zu.

Konfigurieren Sie PAPERLESS_URL mit der korrekten öffentlichen Adresse

Für eine eindeutige öffentliche Adresse konfigurieren Sie PAPIERLOS_URLGeben Sie Protokoll und Port an, falls es sich nicht um den Standardport handelt, aber fügen Sie keinen abschließenden Schrägstrich oder Pfade wie „/“ hinzu. /accounts/login/.

Zum Beispiel:

PAPERLESS_URL=https://documentos.example.com

Diese Variable konfiguriert gemeinsam die Einstellungen für zulässige Hosts, CORS und vertrauenswürdige CSRF-Quellen. Es wandelt nicht automatisch alle Adressen in Äquivalente um. Von dort aus können Sie die Instanz öffnen.

Wenn Sie Paperless unter einem Unterpfad veröffentlichen, z. B. https://example.com/paperlessGeben Sie diesen Pfad nicht in PAPERLESS_URL ein. Für diese Bereitstellung müssen Präfix und Proxy separat konfiguriert werden.

Stellen Sie sicher, dass Docker die Variable empfängt.

Eine Datei .env Es kann verwendet werden, um Werte in Compose zu ersetzen, aber seine Variablen werden nicht automatisch in die Umgebung aller Dienste integriert.

Sie können diesen Codeausschnitt zum bestehenden Paperless-Service hinzufügen:

services:
  webserver:
    environment:
      PAPERLESS_URL: "https://documentos.example.com"

Integrieren Sie die Anpassung, ohne den Rest Ihrer Komposition zu ersetzen. Behalten Sie das Image, die Volumes, die Abhängigkeiten und alle anderen Variablen bei, die Sie bereits verwendet haben.

Falls Sie die Konfiguration lieber in einer Datei speichern möchten, geben Sie dies bitte explizit an:

services:
  webserver:
    env_file:
      - paperless.env

Und innerhalb paperless.env:

PAPERLESS_URL=https://documentos.example.com

Auf mögliche Duplikate prüfen: Wenn eine Variable auch in environmentDieser Wert hat Vorrang vor dem in definierten Wert. env_file.

Die Änderungen werden durch Neuerstellung des Dienstes angewendet.

Nachdem Sie die Variablen geändert haben, führen Sie den Befehl im entsprechenden Compose-Projekt aus:

docker compose up -d --no-deps --force-recreate webserver

Dieses Beispiel setzt voraus, dass die abhängigen Dienste bereits laufen. Es erstellt Paperless neu, ohne die Datenbank und den Rest des Stacks absichtlich anzuhalten.

Ein einfacher Docker Compose Neustart aktualisiert die Containerumgebung nicht. Sie müssen auch keine Volumes löschen, um diese Anpassungen anzuwenden.

Überprüfen Sie den empfangenen Wert:

docker compose exec webserver printenv PAPERLESS_URL

Wenn die erwartete Adresse nicht angezeigt wird, überprüfen Sie die bearbeitete Datei, den Dienst und doppelte Variablen. Wenn Sie Optionen wie z. B. verwenden -f oder einem bestimmten Projektnamen, behält es dieselben Optionen in den Befehlen bei.

Wann sollte man PAPERLESS_CSRF_TRUSTED_ORIGINS verwenden?

PAPERLESS_CSRF_TRUSTED_ORIGINS ist keine veraltete Variable. Ermöglicht die Deklaration zusätzlicher Quellen für CSRF-geschützte Anfragen.

Zum Beispiel für zwei vertrauenswürdige Richtungen:

PAPERLESS_CSRF_TRUSTED_ORIGINS=https://documentos.example.com,https://archivo.example.com

Verwenden Sie spezifische Quellen mit Angabe des Protokolls und Ports, sofern zutreffend. Verwechseln Sie diese Liste nicht mit PAPERLESS_ALLOWED_HOSTS, wobei Hostnamen ohne Protokoll konfiguriert werden.

Die Autorisierung einer Quelle ersetzt weder Domain-, Zertifikats- noch Proxy-Einstellungen. Sie fügt lediglich die Adressen hinzu, die Sie tatsächlich verwenden und kontrollieren.

HTTPS- und Reverse-Proxy-Header prüfen

Der Proxy muss Host und externes Schema korrekt übertragen. Die Änderung des Hosts ist bei Verwendung von Nginx Proxy Manager, Traefik oder Cloudflare Tunnel nicht zwingend erforderlich; sie hängt von deren Konfiguration ab.

Wenn der Browser HTTPS verwendet und der Proxy über HTTP mit Paperless kommuniziert, muss möglicherweise angegeben werden, wie die sichere externe Verbindung erkannt werden soll:

PAPERLESS_PROXY_SSL_HEADER='["HTTP_X_FORWARDED_PROTO", "https"]'

Dieses Format entspricht einer Variablendatei. Aktivieren Sie es nicht, ohne vorher den Proxy zu überprüfen: Sie müssen diesen Header zuverlässig setzen oder überschreiben und dürfen keine beliebigen Werte von externen Clients akzeptieren.

Bei Ketten mit mehreren Proxys sollte das Schema überprüft werden, das den letzten Hop erreicht. Vertrauensoptionen in weitergeleiteten Headern sollten nicht pauschal alle aktiviert werden.

Wenn der Datensatz eine Quelle anzeigt null oder ein Problem mit dem Empfehlungsgeber; überprüfen Sie auch die für das Formular geltende Empfehlungsrichtlinie. Das Projekt-Wiki dokumentiert Zugriffsprobleme im Zusammenhang mit Referrer-Policy: no-referrerDie Korrektur der zulässigen URLs reicht in diesem Fall möglicherweise nicht aus.

Alte Cookies und veraltete Formulare entsorgen

Sobald die Serverkonfiguration korrigiert ist, öffnen Sie die endgültige Adresse erneut und laden Sie das Anmeldeformular neu. Vermeiden Sie es, das Formular von einem alten Tab aus abzusenden oder während des Tests zwischen HTTP, HTTPS, IP und Domain zu wechseln.

Falls das Problem mit Cookies oder Tokens zusammenhängt, versuchen Sie, ein privates Browserfenster zu verwenden oder die Daten einfach von der Paperless-Website zu löschen. Prüfen Sie außerdem, ob Erweiterungen Cookies blockieren oder Anfragen verändern.

Ziel ist es, dass Browser, Proxy und Anwendung hinsichtlich Zugriffsadresse und Kontext übereinstimmen. Das Deaktivieren von CSRF, das wahllose Erweitern von Quellen oder das Löschen von Bereitstellungsdaten behebt die Ursache nicht..