Header Authentication

Header authentication lets a reverse proxy handle login for you. Instead of entering credentials in Reaparr's login form, your reverse proxy authenticates the user and passes their identity in an HTTP header. Reaparr reads that header, finds the matching account, and signs the user in automatically.

This is useful when you already have authentication enforced at the proxy level (nginx basic auth, Authelia, Authentik, etc.) and don't want to manage a separate set of credentials inside Reaparr.

How it works

1. A request reaches your reverse proxy
2. The proxy authenticates the user (via basic auth, OAuth, LDAP, etc.)
3. The proxy injects the X-Auth-User header containing the username or email
4. Reaparr's middleware validates the request came from a trusted proxy IP
5. The header value is matched to an existing Reaparr user account
6. The user is signed in without touching the login form

Prerequisites

• Reaparr must be running behind a reverse proxy
• A user account must already exist in Reaparr whose username (or email) matches the value your proxy will send in the header
• The reverse proxy's IP address must be added to the Trusted Proxies list

Configuration

Header authentication is configured by editing /Config/ReaparrSettings.json directly. After saving your changes, restart the Reaparr container for them to take effect.

The relevant section of the file is nested under AuthenticationSettings → HeaderAuthentication:

{
  "AuthenticationSettings": {
    "ResetCredentials": false,
    "HeaderAuthentication": {
      "Enabled": false,
      "MappingType": "Username",
      "TrustedProxies": [],
      "RequireHttps": true,
      "MaxHeaderLength": 256,
      "EnableLogging": true
    }
  }
}

Header name

The default header Reaparr reads is X-Auth-User. You can change this by setting the AUTH_HEADER_TOKEN environment variable on the Reaparr container (see the Docker Compose example below).

Trusted proxies

Trusted Proxies is deny-by-default — if the list is empty, every request is rejected regardless of headers. Add the IP address or CIDR range of your reverse proxy:

• Single IP: 192.168.1.10
• CIDR range: 192.168.1.0/24
• Docker default bridge: 172.17.0.1
• Localhost: 127.0.0.1
• IPv6 loopback: ::1

Both IPv4 and IPv6 (including CIDR notation up to /128) are supported. If your proxy is in a Docker network, use the gateway IP of that network, not the container IP (which can change).

Reverse proxy examples

nginx — Basic Auth (single shared user)

This setup requires every visitor to provide HTTP basic auth credentials. Once authenticated, nginx injects the X-Auth-User header with a fixed username that maps to your Reaparr account.

Step 1 — Create an htpasswd file

htpasswd -c /etc/nginx/.htpasswd <your-reaparr-username>

Use the same username as your Reaparr account (Mapping Type: Username), or an email address if you use Email mapping.

Step 2 — Configure nginx

server {
    listen 443 ssl;
    server_name reaparr.example.com;

    # Basic auth gate — user must supply valid credentials to proceed
    auth_basic "Reaparr";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://reaparr:7000;

        # Inject the authenticated username as the Reaparr auth header.
        # This value must match an existing Reaparr account username.
        proxy_set_header X-Auth-User <your-reaparr-username>;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Because every visitor who passes basic auth is mapped to the same Reaparr account, this approach works well for a single-user setup. The nginx credential is the only thing guarding access; Reaparr's own login prompt is bypassed entirely.

nginx — External auth (auth_request)

Use this when you have a dedicated auth service (Authelia, Authentik, Vouch, etc.) that returns the authenticated user's identity in a response header.

server {
    listen 443 ssl;
    server_name reaparr.example.com;

    # Delegate authentication to your auth service
    auth_request /auth;

    # Forward the username header returned by the auth service
    auth_request_set $auth_user $upstream_http_x_remote_user;

    location / {
        proxy_pass http://reaparr:7000;

        # Pass the username resolved by the auth service
        proxy_set_header X-Auth-User $auth_user;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Internal endpoint that proxies to your auth service
    location = /auth {
        internal;
        proxy_pass http://authelia:9091/api/verify;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header X-Original-URI $request_uri;
    }
}

The header name returned by your auth service (X-Remote-User in the example) must match what it's configured to emit. Check your auth provider's documentation for the exact header name.

Docker Compose

services:
  reaparr:
    container_name: Reaparr
    image: reaparr/reaparr:latest
    ports:
      - '7000:7000'
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - LOG_LEVEL=INFORMATION
      # Optional: override the default X-Auth-User header name
      - AUTH_HEADER_TOKEN=X-Auth-User
    volumes:
      - /your/config/path:/Config
      - /your/downloads/path:/Downloads
      - /your/movies/path:/Movies
      - /your/tvshows/path:/TvShows

The /Config volume is where ReaparrSettings.json lives. Edit the file, then restart the container:

docker restart Reaparr

Troubleshooting

Header is present but login doesn't happen

• Check that Enabled is set to true in /Config/ReaparrSettings.json and restart the container

Authentication fails even with the correct header value

• Verify the reverse proxy's IP is listed in Trusted Proxies
• In Docker, the gateway IP of the proxy's network is used (e.g., 172.17.0.1), not the container IP

It works locally but fails in production

• Require HTTPS defaults to true. Ensure your proxy is forwarding over HTTPS, or disable the setting for internal networks

The wrong user is being signed in

• Confirm the header value exactly matches the Reaparr account's username (or email if using Email mapping) — it is case-sensitive
• Set EnableLogging to true in ReaparrSettings.json and check Reaparr's logs to see what header value is being received