Paperless-ngx reverse-proxy identity needs header discipline
Paperless-ngx turns scanned documents into a searchable archive. That makes its login, reverse-proxy integration, and document permissions a direct part of the confidentiality boundary. The product supports remote-user authentication for some SSO designs, but its documentation includes a sharp warning: if a reverse proxy passes an external Remote-User header through to the application, authentication can be bypassed.
A ZoomEye query for app="Paperless-ngx" returned 3,791 matches on 28 October 2026, using sub_type=all and a page size of one. A title query returned 3,796. The close counts show a consistent candidate set without proving which deployments enable remote-user authentication or which are reachable from the public internet.
Inspect the trust path
The proxy is the identity source when remote-user authentication is enabled. It must strip any client-supplied header before adding the authenticated value. The application should receive that header only from the trusted proxy, not from a direct connection or a second ingress route. If proxy trust is configured with an address range, verify the actual address observed by the application and test requests from outside that range.
Both the frontend and API remote-user settings have separate switches. Enabling one for a reverse proxy can create a mismatch if the other is enabled without the same header stripping. Review both values, the configured header name, and the login flow. If the application also retains local password login, decide whether that path should remain available to administrators and ordinary users.
PAPERLESS_SECRET_KEY is used for authentication material and must be random and protected. The setup documentation states that failing to use a suitable secret key allows third parties to forge authentication credentials. Store it in a secret manager, limit read access, and plan rotation with the expected session invalidation. A copied compose file or backup that includes the key is a security incident candidate.
Test document boundaries
Authentication is only the first layer. Confirm that users can see only the documents and shares allowed by their groups. Create two test users and try both a direct URL and an API request. Check whether share links cross that boundary by design. Paperless-ngx documents that share links do not require login, so link generation and revocation deserve their own owner and audit.
Use the Paperless-ngx measurement to seed an ownership comparison. Inspect external hosts for header behavior, reverse-proxy configuration, and document access. Do not test with real client documents. Synthetic PDFs and test users are enough to show whether authentication and authorization paths behave as intended.
The response should cover the secret key, proxy header stripping, API access, user groups, share-link policy, and backup encryption. Paperless-ngx is designed to hold sensitive records, so a clean login page is not enough evidence that the archive boundary is sound.
Top comments (0)