NGINX Forward Auth Integration#

Tinyauth integrates with NGINX-based reverse proxies (including NGINX Proxy Manager and Swag) using NGINX's auth_request module. Because auth_request does not support native 302 redirects, Tinyauth uses a dedicated endpoint and a custom response header to work around this limitation 1.

The auth endpoint for NGINX is /api/auth/nginx 2. Requests to this endpoint are handled by the proxy controller, which recognizes nginx as a distinct proxy type and always returns non-browser responses regardless of the incoming User-Agent 3.

How the Auth Flow Works#

NGINX's auth_request module makes a subrequest to /api/auth/nginx. Tinyauth responds:

• Authenticated (200): Sets identity headers (Remote-User, Remote-Name, Remote-Email, Remote-Groups, Remote-Sub) for the upstream app 4.
• Unauthenticated (401) or Forbidden (403): Returns a JSON error and sets the x-tinyauth-location response header with the login/unauthorized URL 5 6.

NGINX is then configured to capture x-tinyauth-location and use it in an error_page directive to perform the redirect:

auth_request /tinyauth;
auth_request_set $redirection_url $upstream_http_x_tinyauth_location;
error_page 401 403 =302 $redirection_url;

7

The /tinyauth internal location proxies to http://tinyauth:3000/api/auth/nginx and must pass the forwarded headers (x-forwarded-host, x-forwarded-uri, x-forwarded-proto) so Tinyauth can reconstruct the original request URL 8. For NGINX, Tinyauth tries the AuthRequest module first, then falls back to ForwardAuth 9.

Key Configuration Requirements#

• Disable "Block Common Exploits" on the Tinyauth host in NGINX Proxy Manager — this feature blocks URLs in query parameters, which Tinyauth requires 10.
• Set TINYAUTH_AUTH_TRUSTEDPROXIES to the NGINX instance IP so Tinyauth can trust X-Real-IP/X-Forwarded-For headers for IP-based ACLs 11.
• For Docker-based NGINX setups, run NGINX in network_mode: host to ensure correct client IP detection 12.

The full NGINX Proxy Manager configuration guide, including a sample Docker Compose file, is at nginx-proxy-manager.mdx.

v5.1.x Regression Fixes#

login_for Optional (v5.1.1 → patched in v5.1.2)#

v5.1.0 added a required login_for query parameter for app redirects. This broke older NGINX setups (e.g., Swag/LinuxServer configs) that used the plain redirect path without the new x-tinyauth-location header, causing post-login redirects to fail 13. The fix (commit 0c1a64d) made login_for optional on the frontend: if absent but redirect_uri is present, the frontend now defaults to /continue instead of /logout 13. The backend still sets login_for=app by default 14.

Root-Domain Redirect Failure (v5.1.0–5.1.1 → fixed in v5.1.2)#

The stricter redirect validation introduced in v5.1.0 via PR #950 caused Tinyauth to reject redirects to root domains (e.g., protecting domain.com when Tinyauth is on tinyauth.domain.com). The isRedirectSafe() function's subdomain check required the redirect hostname to end with ".{cookieDomain}", but the root domain itself never satisfies that condition 15. Fixed in v5.1.2-beta.1; confirmed working by affected users 15.

TOTP + NGINX Post-Login Redirect (v5.1.0–5.1.1 → fixed in v5.1.2)#

After a successful TOTP submission, the frontend navigated to /logout instead of the original redirect_uri. This affected NGINX Proxy Manager users with 2FA enabled. Fixed in v5.1.2-beta.3 after iterative beta testing 15.

Source Pointers#