Виправлення помилки невдалої перевірки CSRF у Paperless-ngx

Якщо відображається Paperless-ngx 403 Заборонено: не вдалося виконати перевірку CSRF Після входу в систему програма відхилила перевірку безпеки запиту. Це поширене явище після зміни домену, увімкнення HTTPS або налаштування зворотного проксі-сервера, але також може бути пов’язано з файлами cookie або застарілою формою.

Рішення включає визначення конкретної причини, перевірку публічної URL-адреси та забезпечення того, щоб конфігурація дійсно досягла Paperless. Вам не потрібно вимикати захист CSRF або змінювати дозволи документа.

Визначте причину помилки CSRF у Paperless-ngx

Django використовує файли cookie та токени, а також перевірку походження запитів, щоб ускладнити надсилання дій іншим вебсайтам, використовуючи сеанс користувача.

Перевірте, чи в повідомленні чітко зазначено Не вдалося перевірити CSRFПомилка 403, згенерована Cloudflare, правилом проксі-сервера або зовнішньою системою доступу, може мати іншу причину.

Якщо ви використовуєте Docker Compose, відтворіть помилку та перевірте журнали:

docker compose logs --tail=100 webserver

У прикладах, які ми використовували webserver як назву служби. Замініть її назвою вашого розгортання. Шукайте посилання на django.security.csrf та причину відмови.

• Перевірка походження не вдалася: Перевірте джерело, яке відображається в повідомленні, та загальнодоступні налаштування.
• Файл cookie CSRF не встановлено: перевірити, чи браузер отримує та зберігає файл cookie.
• Токен відсутній або неправильний: Перезавантажте форму перед її надсиланням.
• Не вдалося перевірити джерело посилання: Перевірте заголовки та доступ через HTTPS.

Налаштуйте PAPERLESS_URL з правильною публічною адресою

Для унікальної публічної адреси налаштуйте БЕЗПАПЕРОВА_URLВкажіть протокол і порт, якщо вони не встановлені за замовчуванням, але не додавайте скісну риску або шляхи, як-от /accounts/login/.

Наприклад:

PAPERLESS_URL=https://documentos.example.com

Ця змінна спільно налаштовує параметри для дозволених хостів, CORS та довірених джерел CSRF. Він не конвертує всі адреси автоматично в еквіваленти з якого можна відкрити екземпляр.

Якщо ви публікуєте Paperless у підшляху, такому як https://example.com/paperlessНе вводьте цей шлях у PAPERLESS_URL. Таке розгортання вимагає окремого налаштування префікса та проксі-сервера.

Переконайтеся, що Docker отримує змінну

Файл .env Його можна використовувати для заміни значень у Compose, але його змінні не автоматично включаються в середовище всіх сервісів.

Ви можете додати цей фрагмент коду до існуючого сервісу Paperless:

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

Інтегруйте налаштування, не замінюючи решту вашого Compose. Збережіть зображення, томи, залежності та інші змінні, які ви вже використовували.

Якщо ви бажаєте зберегти конфігурацію у файлі, будь ласка, чітко вкажіть це:

services:
  webserver:
    env_file:
      - paperless.env

І всередині paperless.env:

PAPERLESS_URL=https://documentos.example.com

Перевірте наявність можливих дублікатів: якщо змінна також з'являється в environment, це значення має пріоритет над тим, яке визначено в env_file.

Застосуйте зміни, повторно створивши службу.

Після зміни змінних виконайте команду з відповідного проєкту Compose:

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

У цьому прикладі припускається, що залежні служби вже запущені. Він відтворює Paperless без навмисної зупинки бази даних та решти стеку.

Простий перезапуск Docker Compose не оновлює середовище контейнера. Вам також не потрібно видаляти томи, щоб застосувати ці налаштування.

Перевірте отримане значення:

docker compose exec webserver printenv PAPERLESS_URL

Якщо очікувана адреса не відображається, перевірте відредагований файл, службу та будь-які дубліковані змінні. Якщо ви використовуєте такі параметри, як -f або певну назву проекту, він зберігає ті самі параметри в командах.

Коли використовувати PAPERLESS_CSRF_TRUSTED_ORIGINS

PAPERLESS_CSRF_TRUSTED_ORIGINS не є застарілою змінною. Дозволяє оголосити додаткові джерела для запитів, захищених CSRF.

Наприклад, для двох надійних напрямків:

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

Використовуйте конкретні джерела, з протоколом і портом, де це можливо. Не плутайте цей список з PAPERLESS_ALLOWED_HOSTS, де імена хостів налаштовуються без протоколу.

Авторизація джерела не замінює налаштування домену, сертифіката чи проксі-сервера. Вона лише додає адреси, які ви фактично використовуєте та контролюєте.

Перевірте HTTPS та заголовки зворотного проксі-сервера

Проксі-сервер повинен правильно передавати хост і зовнішню схему. Зміна хоста не є обов'язковою при використанні Nginx Proxy Manager, Traefik або Cloudflare Tunnel; це залежить від їхньої конфігурації.

Якщо браузер використовує HTTPS, а проксі-сервер зв'язується з Paperless через HTTP, може знадобитися вказати, як розпізнавати безпечне зовнішнє з'єднання:

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

Цей формат відповідає файлу змінних. Не активуйте його без перевірки проксі-сервера: Ви повинні надійно встановити або перезаписати цей заголовок, уникаючи прийняття довільних значень, надісланих зовнішніми клієнтами.

У ланцюгах з кількома проксі-серверами перевірте схему, яка досягає останнього стрибка. Параметри довіри в перенаправлених заголовках не повинні бути ввімкнені за універсальним підходом.

Якщо запис показує джерело null або проблему з рефералом; також перегляньте політику рефералів, що застосовується до форми. У вікі-проекті задокументовано проблеми доступу, пов’язані з Referrer-Policy: no-referrerУ такому випадку виправлення дозволених URL-адрес може бути недостатньо.

Викиньте старі файли cookie та застарілі форми

Після виправлення конфігурації сервера знову відкрийте остаточну адресу та перезавантажте форму входу. Уникайте надсилання її зі старої вкладки або перемикання між HTTP, HTTPS, IP та доменом під час тестування.

Якщо проблема пов’язана з файлами cookie або токенами, спробуйте скористатися вікном анонімного перегляду або просто видалити дані з сайту Paperless. Також перевірте, чи не блокують файли cookie якісь розширення або не змінюють запити.

Мета полягає в тому, щоб браузер, проксі-сервер і програма збігалися за адресою доступу та контекстом. Вимкнення CSRF, безладне розширення джерел або видалення даних розгортання не вирішує проблему..