Solucionar el error CSRF verification failed en Paperless-ngx

Si Paperless-ngx muestra 403 Forbidden: CSRF verification failed al iniciar sesión, la aplicación ha rechazado una comprobación de seguridad de la petición. Es habitual encontrarlo después de cambiar el dominio, activar HTTPS o configurar un proxy inverso, pero también puede estar relacionado con las cookies o con un formulario antiguo.

La solución consiste en identificar el motivo concreto, comprobar la URL pública y asegurarse de que la configuración llega realmente a Paperless. No necesitas desactivar la protección CSRF ni modificar los permisos de los documentos.

Identifica qué está provocando el error CSRF en Paperless-ngx

Django utiliza cookies y tokens, además de comprobaciones del origen de la petición, para dificultar que otra web envíe acciones aprovechando la sesión del usuario.

Comprueba que el aviso menciona expresamente CSRF verification failed. Un 403 generado por Cloudflare, una regla del proxy o un sistema de acceso externo puede tener otra causa.

Si utilizas Docker Compose, reproduce el fallo y consulta los registros:

docker compose logs --tail=100 webserver

En los ejemplos utilizamos webserver como nombre del servicio. Sustitúyelo por el de tu despliegue. Busca referencias a django.security.csrf y al motivo del rechazo.

• Origin checking failed: revisa el origen que aparece en el aviso y la configuración pública.
• CSRF cookie not set: comprueba que el navegador recibe y conserva la cookie.
• Token ausente o incorrecto: vuelve a cargar el formulario antes de enviarlo.
• Referer checking failed: revisa las cabeceras y el acceso mediante HTTPS.

Configura PAPERLESS_URL con la dirección pública correcta

Para una dirección pública única, configura PAPERLESS_URL. Incluye el protocolo y el puerto si no es el predeterminado, pero no añadas una barra final ni rutas como /accounts/login/.

Por ejemplo:

PAPERLESS_URL=https://documentos.example.com

Esta variable configura conjuntamente los ajustes de hosts permitidos, CORS y orígenes CSRF de confianza. No convierte automáticamente en equivalentes todas las direcciones desde las que puedas abrir la instancia.

Si publicas Paperless bajo una subruta, como https://example.com/paperless, no introduzcas esa ruta en PAPERLESS_URL. Ese despliegue requiere configurar por separado el prefijo y el proxy.

Asegúrate de que Docker recibe la variable

Un archivo .env puede servir para sustituir valores en Compose, pero sus variables no se incorporan automáticamente al entorno de todos los servicios.

Puedes añadir este fragmento al servicio existente de Paperless:

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

Integra el ajuste sin sustituir el resto de tu Compose. Conserva la imagen, los volúmenes, las dependencias y las demás variables que ya utilizabas.

Si prefieres guardar la configuración en un archivo, decláralo expresamente:

services:
  webserver:
    env_file:
      - paperless.env

Y dentro de paperless.env:

PAPERLESS_URL=https://documentos.example.com

Revisa posibles duplicados: si una variable aparece también en environment, ese valor tiene prioridad sobre el definido en env_file.

Aplica los cambios recreando el servicio

Después de cambiar las variables, ejecuta el comando desde el proyecto Compose correspondiente:

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

Este ejemplo presupone que los servicios dependientes ya están en ejecución. Recrea Paperless sin detener deliberadamente la base de datos y el resto del stack.

Un simple docker compose restart no actualiza el entorno del contenedor. Tampoco necesitas eliminar volúmenes para aplicar estos ajustes.

Comprueba el valor recibido:

docker compose exec webserver printenv PAPERLESS_URL

Si no aparece la dirección esperada, revisa el archivo editado, el servicio y las variables duplicadas. Si utilizas opciones como -f o un nombre de proyecto específico, conserva esas mismas opciones en los comandos.

Cuándo utilizar PAPERLESS_CSRF_TRUSTED_ORIGINS

PAPERLESS_CSRF_TRUSTED_ORIGINS no es una variable obsoleta. Permite declarar orígenes adicionales para peticiones protegidas por CSRF.

Por ejemplo, para dos direcciones de confianza:

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

Utiliza orígenes concretos, con protocolo y puerto cuando corresponda. No confundas esta lista con PAPERLESS_ALLOWED_HOSTS, donde se configuran nombres de host sin protocolo.

Autorizar un origen no sustituye la configuración del dominio, del certificado o del proxy. Añade únicamente las direcciones que realmente utilizas y controlas.

Revisa HTTPS y las cabeceras del proxy inverso

El proxy debe transmitir correctamente el host y el esquema externo. No es obligatorio que cambie el host por utilizar Nginx Proxy Manager, Traefik o Cloudflare Tunnel: depende de cómo estén configurados.

Si el navegador usa HTTPS y el proxy se comunica por HTTP con Paperless, puede ser necesario indicar cómo reconocer la conexión externa segura:

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

Este formato corresponde a un archivo de variables. No lo actives sin comprobar el proxy: debe establecer o sobrescribir esa cabecera de manera fiable, evitando aceptar valores arbitrarios enviados por clientes externos.

En cadenas con varios proxies, comprueba el esquema que llega al último salto. Las opciones de confianza en cabeceras reenviadas no deben habilitarse todas como receta universal.

Si el registro muestra un origen null o un problema de Referer, revisa también la política de referencia aplicada al formulario. La wiki del proyecto documenta problemas de acceso relacionados con Referrer-Policy: no-referrer. Corregir las URL permitidas puede no bastar en ese caso.

Descarta cookies antiguas y formularios desactualizados

Una vez corregida la configuración del servidor, abre de nuevo la dirección definitiva y vuelve a cargar el formulario de acceso. Evita enviarlo desde una pestaña antigua o alternar entre HTTP, HTTPS, IP y dominio durante la prueba.

Si el motivo apunta a cookies o tokens, prueba con una ventana privada o elimina únicamente los datos del sitio de Paperless. Comprueba también si alguna extensión está bloqueando cookies o modificando las peticiones.

El objetivo es que navegador, proxy y aplicación coincidan en la dirección y el contexto de acceso. Desactivar CSRF, ampliar indiscriminadamente los orígenes o borrar datos del despliegue no resuelve la causa.