Howto Authelia proxy auth

How to set up Authelia forward-auth with Bindery

This guide walks through connecting Authelia's forward-auth middleware to Bindery's proxy auth mode so users sign in via Authelia and land in Bindery without a second login prompt.

What you'll have at the end: Authelia protects the Bindery URL. On first visit, users are redirected to the Authelia login page. After authentication, Authelia forwards the request to Bindery with a Remote-User header; Bindery provisions the user account automatically and issues a session.

Prerequisites:

• Authelia v4.37+ running and accessible
• Traefik v2/v3 (or Caddy/nginx — see variants below) as your reverse proxy
• Bindery reachable on your Docker/Kubernetes network
• You know the Docker bridge network CIDR or pod subnet Traefik runs in

---

Steps

1. Verify Authelia is working

Before touching Bindery, confirm Authelia is protecting at least one other service successfully. If Authelia's own login page loads at https://auth.example.com, you're ready.

2. Register a Bindery access-control rule in Authelia

Add a rule to your Authelia configuration.yml that covers the Bindery domain:

access_control:
  default_policy: deny
  rules:
    # ... your other rules ...
    - domain: bindery.example.com
      policy: one_factor          # or two_factor if you want 2FA for Bindery
      subject: "group:books"      # optional: restrict to a specific Authelia group

Reload or restart Authelia after saving.

Expected result: navigating to https://bindery.example.com before completing the next steps should redirect you to the Authelia login page.

3. Configure Traefik to apply the Authelia middleware to Bindery

Docker Compose (labels)

services:
  bindery:
    image: ghcr.io/vavallee/bindery:latest
    environment:
      BINDERY_TRUSTED_PROXY: "172.20.0.0/16"    # your Docker bridge CIDR
      BINDERY_PROXY_AUTH_HEADER: "Remote-User"   # Authelia's identity header
      BINDERY_PROXY_AUTO_PROVISION: "true"
    labels:
      - traefik.enable=true
      - traefik.http.routers.bindery.rule=Host(`bindery.example.com`)
      - traefik.http.routers.bindery.entrypoints=websecure
      - traefik.http.routers.bindery.tls.certresolver=le
      - traefik.http.routers.bindery.middlewares=authelia@docker
      - traefik.http.services.bindery.loadbalancer.server.port=8787

The authelia@docker middleware must already be defined in your Authelia service labels or in a Traefik static config file. A minimal Authelia middleware definition:

# In your authelia service labels or traefik dynamic config:
- traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.example.com/
- traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true
- traefik.http.middlewares.authelia.forwardauth.authResponseHeaders=Remote-User,Remote-Groups,Remote-Name,Remote-Email

Kubernetes (IngressRoute CRD)

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: authelia
  namespace: default
spec:
  forwardAuth:
    address: http://authelia.default.svc.cluster.local:9091/api/verify?rd=https://auth.example.com/
    trustForwardHeader: true
    authResponseHeaders:
      - Remote-User
      - Remote-Groups
      - Remote-Name
      - Remote-Email
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: bindery
spec:
  entryPoints: [websecure]
  routes:
    - match: Host(`bindery.example.com`)
      kind: Rule
      middlewares:
        - name: authelia
      services:
        - name: bindery
          port: 8787
  tls:
    certResolver: le

Helm values.yaml for the Bindery pod:

env:
  BINDERY_TRUSTED_PROXY: "10.0.0.0/8"           # pod CIDR
  BINDERY_PROXY_AUTH_HEADER: "Remote-User"
  BINDERY_PROXY_AUTO_PROVISION: "true"

4. Enable proxy auth mode in Bindery

Start Bindery with the environment variables from step 3. On first boot, confirm the startup log contains:

trusted proxies: [172.20.0.0/16]

Then set the auth mode to proxy. Either:

• UI: Settings → General → Security → Authentication Mode → select Proxy → Save.
• API:

  curl -X PUT http://bindery:8787/api/v1/auth/mode \
    -H "X-Api-Key: <your-api-key>" \
    -H "Content-Type: application/json" \
    -d '{"mode": "proxy"}'

Expected result: {"mode":"proxy"} in the response. The login page now shows "Sign in via your SSO provider" instead of the password form.

5. Verify end-to-end

1. Open a private/incognito window and navigate to https://bindery.example.com.
2. You should be redirected to https://auth.example.com — log in with your Authelia credentials.
3. After successful login, Authelia redirects back to Bindery. Bindery reads Remote-User, creates or resolves your account, and lands you on the library page.
4. Check Settings → Users — your username should appear as a new account with role user.

Confirm the user was provisioned:

curl -s -H "X-Api-Key: <admin-key>" http://bindery:8787/api/v1/auth/users | jq .

---

Caddy variant

bindery.example.com {
    forward_auth authelia:9091 {
        uri /api/verify?rd=https://auth.example.com/
        copy_headers Remote-User Remote-Groups Remote-Name Remote-Email
    }
    reverse_proxy bindery:8787
}

Bindery env: BINDERY_PROXY_AUTH_HEADER=Remote-User, BINDERY_TRUSTED_PROXY=<caddy-ip-or-cidr>.

nginx variant

location = /authelia {
    internal;
    proxy_pass http://authelia:9091/api/verify;
    proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
    proxy_set_header Content-Length "";
    proxy_pass_request_body off;
}

location / {
    auth_request /authelia;
    auth_request_set $user $upstream_http_remote_user;
    proxy_set_header Remote-User $user;
    proxy_pass http://bindery:8787;
}

Bindery env: BINDERY_PROXY_AUTH_HEADER=Remote-User, BINDERY_TRUSTED_PROXY=<nginx-ip>.

---

Failure modes

What you see	Likely cause	Fix
Bindery refuses to start: proxy mode requires BINDERY_TRUSTED_PROXY	Env var not set	Add BINDERY_TRUSTED_PROXY with the Traefik/nginx IP or Docker bridge CIDR
Redirected to Authelia login, but after login you get Bindery 401 Unauthorized	Traefik container IP not in BINDERY_TRUSTED_PROXY	Check startup log for trusted proxies: [...]; update CIDR to include the Traefik pod/container IP
Redirected to Authelia login, after login you get Bindery 401 Unauthorized	authResponseHeaders missing Remote-User in middleware definition	Verify the Traefik middleware has authResponseHeaders: [Remote-User, ...] and Authelia is setting that header on success
Login page still shows password form	Auth mode not set to proxy	Run GET /api/v1/auth/status and confirm "mode": "proxy"; set it via Settings or the API
New Bindery user created every time you rename your Authelia account	Remote-User maps to a mutable username	See docs/auth-proxy.md — Header choice
OPDS / API scripts get 401 after enabling proxy mode	Clients don't go through Authelia	Exempt /opds/* and /api/* from Authelia's forwardauth in your access-control rules; those paths use X-Api-Key directly

For more, see Troubleshooting.