Proxy Authentication and Redirect Flow#

internal/controller/proxy_controller.go is the single entry point for all reverse-proxy authentication checks. The route GET/ANY /api/auth/:proxy accepts a proxy identifier (traefik, caddy, envoy, nginx) and delegates to proxyHandler, which:

1. Resolves a ProxyContext (host, proto, path, auth module type) from forwarded headers
2. Runs the policy engine rule chain
3. Returns 200 (allow), 302 (browser redirect), or 401/403 + x-tinyauth-location (non-browser)

Request Context Extraction by Proxy Type#

getProxyContext determines which auth module(s) to try based on the proxy type 1:

Modules are tried in order; the first to succeed wins 2.

Path Normalization Before ACL Evaluation#

After resolving the context, getProxyContext sanitizes the path 3 before it is passed to the policy engine:

1. Parses ctx.Path with url.Parse
2. Rejects paths that contain a host component or don't start with /
3. Strips query parameters — only upath.Path is used
4. Normalizes with path.Clean

This normalization was added in PR #1055 to close ACL bypass vectors via dot segments (/foo/../admin), percent-encoding (/%61dmin), and query-string tricks (e.g., x-forwarded-uri: /public?next=/admin). An earlier fix in PR #1044 had introduced getRequestPath() per-module to partially address path parsing from x-forwarded-uri, but the comprehensive sanitization landed in PR #1055.

Security implication: Without normalization, a crafted x-forwarded-uri could trick a path allow rule into granting access to protected resources. Malformed URIs now return 400.

ACL Rule Chain and Browser Detection#

proxyHandler runs rules in strict sequence; each short-circuits on a definitive outcome (see Policy Engine for full detail):

1. RuleIPBypassed — client IP in bypass list → 200, skip auth
2. RuleAuthEnabled — path matches path.allow (and not blocked) → 200, skip auth
3. RuleIPAllowed — IP blocked or not in allow list → 403 /unauthorized
4. RuleUserAllowed / RuleOAuthGroup / RuleLDAPGroup — user/group checks → 403 or continue
5. Unauthenticated → 401 redirect to /login

PR #1044 reworked RuleAuthEnabled's path matching to use matchPathRule(): plain strings are treated as prefix matches, patterns wrapped in /…/ are treated as regexes, and invalid patterns default to EffectDeny (preventing silent bypass).

Browser vs. non-browser response is decided by useBrowserResponse: Nginx always gets 401/403 JSON + x-tinyauth-location header (regardless of User-Agent), while Traefik/Caddy/Envoy check the User-Agent against Chrome|Gecko|AppleWebKit|Opera|Edge 4.

Forward-Auth Redirect Flow#

When a request is unauthenticated and a browser response is appropriate, the proxy controller builds a login redirect 5:

redirect_uri = proto://host/path (reconstructed from ProxyContext)
→ 302 to {APP_URL}/login?redirect_uri=...&login_for=app

The login_for=app parameter tells the OAuth/login callback to route the post-login redirect to /continue?redirect_uri=... rather than an OIDC flow. On the /continue page, the frontend validates the redirect_uri via isRedirectSafe() and sends the user to the original URL.

login_for is optional since v5.1.2: older NGINX setups (e.g., Swag/LinuxServer configs) that didn't pass login_for were broken in v5.1.0–5.1.1 because the frontend required it to determine the post-login destination. The fix made login_for optional — if absent but redirect_uri is present, the frontend defaults to /continue 6.

TOTP continuation: After a successful TOTP submission, the frontend must navigate to /continue?redirect_uri=... to complete the flow. A v5.1.0–5.1.1 bug caused the frontend to navigate to /logout instead, affecting all users with 2FA enabled on NGINX setups. Fixed in v5.1.2-beta.3 6.

OIDC Callback Redirect URI Construction#

In oidc_controller.go, authorizeComplete() constructs the final redirect URI:

1. Parsing authorizeReq.RedirectURI with url.Parse
2. Calling cu.Query() to extract existing query parameters
3. Setting/overwriting code and (if non-empty) state
4. Re-encoding via cu.RawQuery = q.Encode()

This preserves any pre-existing params in the redirect_uri. Before PR #1003, the code used fmt.Sprintf("%s?%s", ...), which always appended a ? regardless of whether params already existed — causing malformed URLs like ?provider=oidc?code=... for apps such as Hister that require a query param in their callback URL 7. The same pattern was applied to authorizeError() to preserve callback query params on error responses.

Redirect Safety Validation#

isRedirectSafe() in oauth_controller.go validates any redirect_uri before the frontend executes it. It applies two phases:

1. Exact host match — validates the redirect URI host against APP_URL via a domain validator (port-aware). Returns true if it passes.
2. Subdomain match (if ENABLE_SUBDOMAINS=true) — checks whether the redirect hostname ends with .<cookieDomain> or exactly equals cookieDomain.

A failure at both phases causes the frontend to navigate to /logout instead of the intended redirect_uri 6.

v5.1.0–5.1.1 regression: The Phase 2 check required the redirect hostname to end with ".<cookieDomain>". The root domain itself (e.g., domain.com) never satisfies this when cookieDomain is also domain.com, so protecting a root domain with Tinyauth on a subdomain broke post-login redirect. Fixed in v5.1.2-beta.1 by also allowing an exact match against cookieDomain 6.