Howto Authentik proxy auth

How to set up Authentik forward-auth with Bindery

This guide connects Authentik's embedded outpost (forward-auth provider) to Bindery's proxy auth mode. Users sign in at Authentik and land in Bindery without a second login prompt.

What you'll have at the end: Authentik's proxy provider protects the Bindery URL. On first visit, users are redirected to Authentik. After authentication, Authentik's outpost forwards X-Authentik-Username to Bindery; Bindery provisions the account and issues a session.

Prerequisites:

• Authentik v2023.x+ running and accessible
• Caddy (preferred) or Traefik as your reverse proxy
• Bindery reachable on your Docker/Kubernetes network
• Admin access to the Authentik UI

---

Steps

1. Create a Proxy Provider in Authentik

1. In the Authentik admin UI, go to Applications → Providers → Create.
2. Choose Proxy Provider.
3. Fill in:
   • Name: bindery
   • Authorization flow: your default authorization flow (e.g. default-provider-authorization-implicit-consent)
   • Mode: Forward auth (single application)
   • External host: https://bindery.example.com
4. Click Finish.

Expected result: the provider appears in the list with type "Proxy".

2. Create an Application linked to the provider

1. Go to Applications → Applications → Create.
2. Fill in:
   • Name: Bindery
   • Slug: bindery
   • Provider: select the provider created in step 1
3. Click Create.

3. Add Bindery to the Embedded Outpost

1. Go to Applications → Outposts.
2. Edit the authentik Embedded Outpost.
3. Under Applications, add Bindery.
4. Click Update.

Expected result: within ~30 seconds, the outpost picks up the new application. You can verify by checking System → Tasks — look for a recent outpost sync task.

4. Configure your reverse proxy

Caddy (recommended)

bindery.example.com {
    forward_auth authentik:9000 {
        uri /outpost.goauthentik.io/auth/caddy
        copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email X-Authentik-Name
        # Trust only the outpost — do not copy X-Authentik-* from untrusted upstreams
    }
    reverse_proxy bindery:8787
}

Traefik (Docker labels)

# In your Authentik outpost service or a separate middleware definition:
labels:
  - traefik.http.middlewares.authentik.forwardauth.address=http://authentik:9000/outpost.goauthentik.io/auth/traefik
  - traefik.http.middlewares.authentik.forwardauth.trustForwardHeader=true
  - traefik.http.middlewares.authentik.forwardauth.authResponseHeaders=X-Authentik-Username,X-Authentik-Groups,X-Authentik-Email,X-Authentik-Name

# On the Bindery service:
  - traefik.http.routers.bindery.middlewares=authentik@docker

5. Set Bindery environment variables

# Docker Compose or Helm values.yaml
environment:
  BINDERY_TRUSTED_PROXY: "172.20.0.0/16"         # Docker bridge or pod CIDR
  BINDERY_PROXY_AUTH_HEADER: "X-Authentik-Username"
  BINDERY_PROXY_AUTO_PROVISION: "true"

Stability note: X-Authentik-Username changes if a user's username is renamed in Authentik. For production installs, configure a custom property mapping that exposes the user's UUID in a header (e.g. X-Authentik-UID) and use that instead. See docs/auth-proxy.md — Header choice.

6. Enable proxy auth mode in Bindery

Start Bindery and confirm the startup log shows:

trusted proxies: [172.20.0.0/16]

Then set auth mode to proxy:

• UI: Settings → General → Security → Authentication Mode → 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"}. The login page shows "Sign in via your SSO provider".

7. Verify end-to-end

1. Open a private/incognito window and navigate to https://bindery.example.com.
2. You are redirected to Authentik's login page — log in.
3. After authentication, Authentik redirects back. Bindery reads X-Authentik-Username, provisions your account, and shows the library.
4. Check Settings → Users — your username should appear as a new user-role account.

Confirm via API:

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

---

Restricting access by Authentik group

In Authentik, edit the Policy/Group bindings on the Bindery application to restrict which groups can access it:

1. Go to Applications → Applications → Bindery → Policy/Group bindings.
2. Click Bind existing group and select the group(s) allowed to use Bindery.

Users outside those groups will be denied at Authentik before Bindery is even reached.

---

Failure modes

What you see	Likely cause	Fix
Bindery refuses to start: proxy mode requires BINDERY_TRUSTED_PROXY	Env var not set or empty	Add BINDERY_TRUSTED_PROXY matching the outpost/proxy container IP or CIDR
After Authentik login, Bindery returns 401 Unauthorized	Outpost IP not in BINDERY_TRUSTED_PROXY	Check startup log for trusted proxies: [...]; widen CIDR to include the Authentik outpost pod/container
After Authentik login, Bindery returns 401 Unauthorized	X-Authentik-Username header not forwarded	Verify copy_headers (Caddy) or authResponseHeaders (Traefik) includes X-Authentik-Username. Enable BINDERY_LOG_LEVEL=debug to see which headers Bindery receives
Login page still shows password form	Auth mode not set to proxy	Confirm with GET /api/v1/auth/status; set mode via Settings or API
Outpost returns 404 on /outpost.goauthentik.io/auth/caddy	Bindery not added to the outpost	Go to Authentik → Outposts → Embedded Outpost → add the Bindery application
OPDS client / API scripts return 401	Client bypasses the outpost	Exempt /opds/* and /api/* from the outpost in Authentik's application policy, or configure the proxy to pass those paths through unauthenticated (Bindery's own X-Api-Key auth still applies)
New user created after Authentik username rename	Mutable X-Authentik-Username used as identifier	Switch to a UUID-based header — see docs/auth-proxy.md; merge the orphaned account from Settings → Users

For more, see Troubleshooting.