SSO Header Authentication (Pro)

By default, TaskTrove and TaskTrove Pro authenticate users with a password.

TaskTrove Pro can piggyback on an upstream reverse proxy (NGINX, Traefik, Envoy, etc.) to provide seamless single sign-on. The proxy is responsible for authenticating users and injecting a trusted header (for example Remote-User) before requests reach the app. When header auth is enabled, TaskTrove Pro detects the username from the header, issues a local session, and sends the browser through the normal /signin flow but without requiring you to enter your password.

Prerequisites

• You are running the Pro build with HTTPS termination handled by a reverse proxy under your control.
• The proxy authenticates users (e.g., SAML, OAuth2, Kerberos) and forwards a canonical username in a header.
• A user has been created in TaskTrove Pro with the same username as the canonical header username.
• Requests reaching TaskTrove already pass through your trusted proxy; the app does not filter by IP, meaning without a secure proxy, anyone can bypass authentication if they know the username.

Configuration

Set the following environment variables for the apps/web.pro container or process:

Variable	Required	Description
SSO_HEADER_AUTH_ENABLED	✅	Set to true to activate header-based SSO. Defaults to false.
AUTH_URL	✅	Public base URL for redirects when running behind a proxy (prevents internal hostnames in /signin redirects).
SSO_HEADER_AUTH_USERNAME_HEADER	optional	Name of the header that carries the authenticated username. Defaults to Remote-User.

Example Docker configuration:

services:
  tasktrove-pro:
    image: ghcr.io/dohsimpson/tasktrove-pro
    environment:
      - SSO_HEADER_AUTH_ENABLED=true
      - SSO_HEADER_AUTH_USERNAME_HEADER=Remote-User
      - AUTH_URL=https://tasktrove.example.com
      - ...

Proxy Responsibilities

1. Authenticate the user using your IdP.
2. Inject the username header before forwarding the request downstream.
3. Strip the header from untrusted traffic. Because TaskTrove Pro now trusts whatever header arrives, your proxy must ensure only authenticated internal traffic can reach the app.

Popular Self-Host SSO Proxies

Most homelab setups already rely on an identity-aware proxy or forward-auth service. Regardless of which tool you choose, TaskTrove Pro only needs two guarantees:

1. Authenticated-only traffic: The proxy must block unauthenticated users before requests reach TaskTrove.
2. Username header injection: After successful auth, the proxy sets the header defined by SSO_HEADER_AUTH_USERNAME_HEADER (default Remote-User).

Below is a high-level breakdown of how common tools satisfy those requirements. Think through your entire user journey (login → forwarded header → TaskTrove session) before choosing one, especially if you host multiple users.

• Authelia (forward auth with NGINX/Traefik): Authelia’s verify endpoint can emit Remote-User and related headers whenever set_remote_user are enabled. Each user authenticates against Authelia (via TOTP, WebAuthn, etc.), and the proxy forwards the approved username downstream so TaskTrove instantly knows which account to use. To read more about how to set up Authelia header auth, see Authelia Trusted Header SSO
• Authentik: Authentik proxy/outpost deployments automatically add headers like X-authentik-username, X-authentik-email, and X-authentik-groups for every authenticated user. You can also define additionalHeaders (for example REMOTE-USER) via group/user attributes or property mappings so TaskTrove receives the exact username header it expects. See the Authentik header auth guide for the current header list and customization options.
• Pangolin: Pangolin forwards identity headers (Remote-User, Remote-Email, Remote-Name) whenever it has user information and drops them if authentication fails. Point your upstream application at Pangolin so every user who passes single sign-on arrives at TaskTrove with Remote-User already set; refer to the Forwarded Headers documentation for supported fields.
• Traefik ForwardAuth / middleware chains: Traefik’s forwardAuth middleware copies headers returned by the auth service that you list in authResponseHeaders (or match via authResponseHeadersRegex). This lets you keep your favorite authentication portal (OAuth2-Proxy, Keycloak Gatekeeper, etc.) while Traefik injects the per-user header TaskTrove needs.
• Plain NGINX with auth_request: The auth_request module exposes upstream values such as $upstream_http_remote_user; combining auth_request_set with proxy_set_header Remote-User $upstream_http_remote_user hands the backend the verified username. Your internal auth endpoint can hook into LDAP, Kerberos, or any multi-user directory—as long as it sets Remote-User only after a successful check.
• Whatever other proxy you use, the same pattern applies: authenticate first, then forward a stable username header.

Troubleshooting

• Verify SSO_HEADER_AUTH_ENABLED is set to true and restart TaskTrove after changing env vars.
• Confirm the proxy is sending the header name referenced by SSO_HEADER_AUTH_USERNAME_HEADER (falls back to Remote-User). Typos or case mismatches mean the header is ignored.
• Tail your TaskTrove logs and look for [Header Auth] entries to confirm when a header triggers the SSO flow or when a username fails validation.
• If users loop on /signin, clear old cookies and make sure the proxy injects the header on the initial request instead of only after redirects.
• AUTH_URL is required for SSO header auth. Without it, redirects may use the internal Docker hostname and break the SSO flow.
• Still stuck? Open an issue