Trusted Proxy and Client IP Resolution#

Overview#

Tinyauth relies on the upstream reverse proxy (Traefik, Caddy, Nginx, Envoy) to forward the real client IP in headers like X-Real-IP or X-Forwarded-For. Because Tinyauth itself sits behind a Docker bridge or load balancer, it cannot determine the actual end-user IP from the raw TCP connection. The TrustedProxies configuration tells Gin which upstream IP addresses are authoritative sources of those headers.

Without trusted proxies configured, all IP-based access controls are silently disabled — IP allow/block rules pass through without effect, and IP bypass rules never fire.

Configuration#

Auth.TrustedProxies is a []string slice in AuthConfig accepting individual IPv4/IPv6 addresses or CIDR ranges.

• Env var: TINYAUTH_AUTH_TRUSTEDPROXIES (comma-separated)
• YAML key: auth.trustedProxies
• Default: empty (feature disabled)

Docker hostname limitation: Gin only accepts IPv4/IPv6 IPs and CIDRs — not Docker service hostnames. For Docker Compose deployments, configure the subnet CIDR of the shared network instead (e.g., 172.20.0.0/16). 1

For NGINX Proxy Manager, the docs recommend setting TINYAUTH_AUTH_TRUSTEDPROXIES to the NGINX instance IP and running NGINX in network_mode: host for correct IP passthrough. 2

Startup Behavior#

During router setup in setupRouter():

1. If Auth.TrustedProxies is non-empty → calls engine.SetTrustedProxies(...) and sets runtime.TrustedProxiesConfigured = true.
2. If empty → calls engine.SetTrustedProxies(nil) (disabling Gin's proxy trust entirely) and logs a warning: "Trusted proxies are not configured, IP access controls will NOT work".

The TrustedProxiesConfigured boolean is stored in RuntimeConfig and propagated into every ACLContext at request time.

How the Policy Engine Uses It#

At the start of each auth request, proxyHandler calls c.ClientIP() (Gin's method, which reads the forwarded header only when the upstream IP is trusted) and builds an ACLContext containing the resolved IP and the TrustedProxiesConfigured flag.

The flag gates two IP-specific rules evaluated in order before any user authentication:

RuleIPBypassed#

IPBypassedRule — If TrustedProxiesConfigured is false, immediately returns EffectDeny (i.e., bypass never activates). Otherwise, merges the global Auth.IP.Bypass list with the per-app ip.bypass list and returns EffectAllow if the client IP matches any entry.

RuleIPAllowed#

IPAllowedRule — If TrustedProxiesConfigured is false, immediately returns EffectAllow (passes everything through, avoiding false blocks behind Docker bridges). Otherwise:

1. Merges global Auth.IP.Block + per-app ip.block — if the IP matches any entry → EffectDeny.
2. Merges global Auth.IP.Allow + per-app ip.allow — if the IP matches any entry → EffectAllow.
3. If an allow list exists but the IP isn't in it → EffectDeny.
4. If neither list has entries → EffectAllow.

Merge semantics: Global lists and per-app lists are concatenated at evaluation time — a global block applies even if the per-app allow list would otherwise permit the IP. 3

IP Filtering Configuration Reference#

Global IP config is defined in IPConfig; per-app config in AppIP.

Key Files#