chore(auth): require trusted proxy for header identity auth

[stuxf]

Relevant issues

Pre-Submission checklist

• I have added testing in the tests/test_litellm/ directory.
• My PR passes all unit tests on make test-unit.
• My PR's scope is as isolated as possible, it only solves 1 specific problem.
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Type

🐛 Bug Fix

Changes

This PR hardens header-derived identity auth. These flows are intended for deployments where a trusted reverse proxy authenticates the user and injects identity headers before requests reach LiteLLM. Previously, LiteLLM trusted those headers without verifying that the direct client was actually the trusted proxy.

1. Trusted proxy gate — added general_settings.trusted_proxy_ranges, a CIDR allowlist for reverse proxies allowed to supply identity headers. Header-based auth now fails closed unless the direct TCP peer is inside one of those ranges. This check intentionally uses the direct client IP, not X-Forwarded-For, because the direct peer is the actor supplying the identity headers.
2. OAuth2-proxy identity allowlist — handle_oauth2_proxy_request still rejects any oauth2_config_mappings field outside ALLOWED_OAUTH2_PROXY_FIELDS = {user_id, user_email, team_id, team_alias, org_id, models}. This prevents forged headers from setting user_role, budgets, limits, permissions, metadata, or future privileged fields.
3. Custom UI SSO gate — enterprise custom UI SSO now validates the trusted proxy range before invoking the configured custom sign-in handler. The built-in CustomSSOLoginHandler also validates before reading x-litellm-user-* headers.

Files

• New: litellm/proxy/auth/trusted_proxy_utils.py — shared trusted-proxy CIDR parsing and fail-closed request validation.
• Modified: litellm/proxy/auth/oauth2_proxy_hook.py — validates trusted proxy before consuming mapped identity headers.
• Modified: enterprise/litellm_enterprise/proxy/auth/custom_sso_handler.py and litellm/integrations/custom_sso_handler.py — validate trusted proxy before custom UI SSO header consumption.
• Modified: litellm/proxy/_types.py — documents general_settings.trusted_proxy_ranges.
• Tests: tests/test_litellm/proxy/auth/test_oauth2_proxy_hook.py covers missing/untrusted/trusted proxy cases plus identity-only mapping; tests/test_litellm/proxy/management_endpoints/test_ui_sso.py covers custom UI SSO rejecting untrusted direct clients before custom handler execution.

Behaviour notes for operators

• Deployments using enable_oauth2_proxy_auth must set general_settings.trusted_proxy_ranges to the CIDR range of the reverse proxy that injects the configured identity headers.
• Deployments using custom_ui_sso_sign_in_handler must do the same before the custom handler can consume x-litellm-* or other identity headers.
• For local-only proxy handoff, use the loopback range such as 127.0.0.1/32 or ::1/128 as appropriate.

[greptile-apps]

Greptile Summary

This PR hardens header-derived identity auth by adding a CIDR-based trusted proxy gate (general_settings.trusted_proxy_ranges) and an identity-only allowlist (ALLOWED_OAUTH2_PROXY_FIELDS) for the OAuth2-proxy hook, custom UI SSO enterprise handler, and base CustomSSOLoginHandler. The new trusted_proxy_utils.py module is the shared enforcement point.

• P1 – unhandled TypeError in _is_ip_in_networks: On dual-stack hosts (uvicorn bound to ::) the direct TCP peer for an IPv4 connection is reported as ::ffff:x.x.x.x. Comparing that IPv6Address against an IPv4Network raises TypeError, which escapes the try/except ValueError at lines 73–76 and results in a 500 for every legitimate proxy request on such deployments.

Confidence Score: 3/5

Do not merge until the IPv4-mapped IPv6 TypeError in _is_ip_in_networks is fixed; dual-stack deployments will receive 500 errors on every legitimate proxy auth request.

One P1 logic bug in the new core enforcement utility (TypeError escaping the except block for IPv4-mapped IPv6 addresses) pulls the score below the P1 ceiling of 4. The security intent and allowlist/gate design are correct, but the bug would break dual-stack deployments reliably.

litellm/proxy/auth/trusted_proxy_utils.py — specifically _is_ip_in_networks (lines 68–77) needs a TypeError catch or IPv4-mapped address unwrapping before the addr-in-network comparison.

Important Files Changed

Filename	Overview
litellm/proxy/auth/trusted_proxy_utils.py	New shared utility for CIDR-based trusted proxy validation; contains a P1 bug where comparing IPv4-mapped IPv6 addresses against IPv4 networks raises an unhandled TypeError, and re-parses CIDR ranges on every auth request.
litellm/proxy/auth/oauth2_proxy_hook.py	Adds trusted-proxy gate and identity-only allowlist (ALLOWED_OAUTH2_PROXY_FIELDS) before consuming mapped identity headers; dead max_budget branch cleaned up; logic is sound.
enterprise/litellm_enterprise/proxy/auth/custom_sso_handler.py	Adds trusted-proxy validation before invoking the custom UI SSO handler; OpenID import moved inside method; logic is correct.
litellm/integrations/custom_sso_handler.py	Base CustomSSOLoginHandler now validates the trusted proxy before reading x-litellm-user-* headers; creates a redundant double-check when called through EnterpriseCustomSSOHandler.
litellm/proxy/_types.py	Adds trusted_proxy_ranges field to ConfigGeneralSettings; clean schema-only addition.
tests/test_litellm/proxy/auth/test_oauth2_proxy_hook.py	New test file covering trusted-proxy rejection, identity allowlist enforcement, and the primary privesc attack path; all mock-only, no real network calls.
tests/test_litellm/proxy/management_endpoints/test_ui_sso.py	Existing tests updated to configure trusted_proxy_ranges and client.host; new test verifies untrusted direct client is rejected before the custom handler is called.

_{Reviews (3): Last reviewed commit: "chore(auth): require trusted proxy for h..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 72.85714% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/auth/trusted_proxy_utils.py	71.69%	15 Missing ⚠️
litellm/integrations/custom_sso_handler.py	0.00%	3 Missing ⚠️
litellm/proxy/auth/oauth2_proxy_hook.py	92.30%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[veria-ai]

Identity-only allowlist and trusted-proxy CIDR gate for header-based auth

This PR adds an allowlist restricting mappable fields to identity-only assertions and a CIDR-based trusted-proxy check that validates the direct TCP peer before trusting any identity headers. Without these controls, oauth2_config_mappings could map attacker-controlled headers to privileged UserAPIKeyAuth fields like user_role, enabling privilege escalation. Both mechanisms fail closed (reject if unconfigured). The implementation correctly uses request.client.host rather than X-Forwarded-For and validates mapping keys (not header values) against the allowlist.

---

Status: 0 open
Risk: 1/10

[stuxf]

@greptile review

[stuxf]

@greptileai review

[greptile-apps]

Unhandled TypeError for IPv4-mapped IPv6 addresses

Python's ipaddress module raises TypeError (not ValueError) when you check IPv6Address in IPv4Network or vice versa. On dual-stack deployments where uvicorn binds to :: (IPv6), the peer address for an IPv4 connection is often reported as ::ffff:127.0.0.1. If trusted_proxy_ranges is configured with IPv4 CIDRs like 127.0.0.1/32, the addr in network comparison raises TypeError, which escapes the try/except ValueError block and propagates as an unhandled exception — resulting in a 500 for every legitimate proxy request on such deployments.

def _is_ip_in_networks(
    client_ip: Optional[str], networks: List[TrustedProxyNetwork]
) -> bool:
    if not client_ip or not networks:
        return False
    try:
        addr = ipaddress.ip_address(client_ip.strip())
    except ValueError:
        return False
    try:
        return any(addr in network for network in networks)
    except TypeError:
        # IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1) vs. IPv4Network —
        # unwrap and retry against IPv4 networks when possible
        if getattr(addr, "ipv4_mapped", None) is not None:
            mapped = addr.ipv4_mapped
            return any(mapped in n for n in networks if n.version == 4)
        return False