4.5 KiB
4.5 KiB
status, created, owner
| status | created | owner |
|---|---|---|
| building | 2026-08-15 | tbd |
Trusted Proxies for X-Forwarded-For
Why
Behind a reverse proxy, Kandev records the proxy's IP as the login session IP
(Settings > Account > Security) and keys the login rate limiter on it, even
when the proxy forwards the real client in X-Forwarded-For. Operators who
front Kandev with a proxy have no way to make the recorded IP match the actual
client.
What
- Kandev SHALL read
server.trustedProxiesfrom startup YAML as a list of IP addresses or CIDR ranges. TheKANDEV_TRUSTED_PROXIESenvironment variable remains a comma-separated override for the same setting. - The environment value SHALL override the YAML value when both are present.
- When the TCP peer of a request is in the trusted list, the client IP SHALL
resolve from the first valid forwarded-IP header in gin's configured order
(
X-Forwarded-For, thenX-Real-IP), falling back to the peer only when neither header yields a valid address. - When the configured list is unset or empty, or the peer is not in the list, the client IP SHALL be the TCP peer; forwarded headers are ignored.
- When any entry fails to parse as an IP or CIDR, startup SHALL log a warning naming the bad value(s) and the whole configured list SHALL be ignored (fail closed; no partial trust). Startup SHALL NOT fail.
- The resolved client IP feeds the same consumers as today: the session IP
recorded for login, setup, invite acceptance, and plugin-provided SSO
(
AuthenticateExternal), and the login rate-limiter key.
Failure modes
- Invalid entries. A warning names the bad values and the configured list is
ignored entirely;
X-Forwarded-Foris never trusted and the recorded IP stays the TCP peer. No crash. - No valid forwarded-IP header on a request from a trusted peer: gin
falls back to the TCP peer (only when neither
X-Forwarded-FornorX-Real-IPyields a valid address). - Spoofing. An operator who configures the list while the backend is directly reachable lets any caller whose peer address falls inside a configured trusted IP/CIDR forge the client IP, including the login rate-limiter key. Callers outside every configured range still fall back to their own peer address. This is a documented tradeoff; network placement stays the operator's responsibility.
Scenarios
- GIVEN
server.trustedProxiesunset andKANDEV_TRUSTED_PROXIESunset, WHEN a login request arrives from a proxy carryingX-Forwarded-For: <client>, THEN the session IP is the proxy's address (the TCP peer). - GIVEN
server.trustedProxies: [10.0.0.0/8]and a request whose TCP peer is10.0.0.5, WHEN the request carriesX-Forwarded-For: 203.0.113.7, THEN the login session IP is203.0.113.7. - GIVEN
server.trustedProxies: [192.168.0.0/16]and a request whose TCP peer is10.0.0.5, WHEN the request carriesX-Forwarded-For: 203.0.113.7, THEN the session IP is10.0.0.5(header ignored). - GIVEN
server.trustedProxies: [10.0.0.0/8, not-a-cidr], WHEN the backend starts, THEN a startup warning namesnot-a-cidrandX-Forwarded-Foris ignored entirely. - GIVEN
KANDEV_TRUSTED_PROXIES=10.0.0.0/8and a backend reachable directly, WHEN a caller whose peer address is10.0.0.6(inside the trusted range) sendsX-Forwarded-For: <forged>, THEN the forged IP is recorded (documented operator tradeoff). - GIVEN
KANDEV_TRUSTED_PROXIES=10.0.0.0/8and a backend reachable directly, WHEN a caller whose peer address is203.0.113.99(outside every trusted range) sendsX-Forwarded-For: <forged>, THEN the forged header is ignored and the session IP is203.0.113.99. - GIVEN a trusted peer, WHEN a request carries no
X-Forwarded-Forand noX-Real-IPheader, THEN the session IP is the TCP peer. - GIVEN a trusted peer, WHEN a request carries only
X-Real-IP: 203.0.113.7, THEN the session IP is203.0.113.7. - GIVEN a trusted peer, WHEN a request carries
X-Forwarded-For: not-an-ipandX-Real-IP: 203.0.113.7, THEN the session IP is203.0.113.7(gin skips the malformed header and reads the next configured one).
Out of scope
- No change to
X-Forwarded-Protohandling (session cookie secure flag, update checks), WebSocketremote_addrlogging, orRequestLoggerfields. - No proxy auto-detection, no launcher CLI flag, no UI changes.
- No per-consumer overrides: the trusted-proxy list applies to every
ClientIP()consumer, exactly as the unconfigured default does today.