Support IP allowlisting behind reverse proxies using trusted forwarded client IP headers

[andrewshaodev]

Summary

Support IP allowlisting when Pangolin is deployed behind reverse proxies (e.g. Cloudflare) by allowing access rules to evaluate trusted forwarded client IP headers.

Motivation

When Pangolin is deployed behind Cloudflare with proxying enabled, all incoming requests originate from Cloudflare IP ranges. This makes Pangolin’s IP allowlisting feature unusable, since allowlisting all Cloudflare IPs defeats the purpose of IP-based access control.

Cloudflare (and other reverse proxies) forward the real client IP using headers such as CF-Connecting-IP and X-Forwarded-For, but Pangolin currently does not use these headers for access control decisions.

This limitation forces users to either:

Disable Cloudflare proxying (losing WAF/DDoS protection), or

Move all IP-based access control outside Pangolin, or

Abandon IP allowlisting entirely

Supporting trusted forwarded IP headers would enable secure and practical IP allowlisting in common real-world deployments.

Proposed Solution

Add optional support for evaluating client IPs from forwarded headers only when requests originate from trusted reverse proxies.

A secure implementation could include:

A configuration option to define trusted proxy IP ranges (e.g. Cloudflare IPs)

Extraction of the real client IP from:

CF-Connecting-IP (preferred)

X-Forwarded-For (left-most value)

IP allow/deny rules evaluated against the extracted client IP

Disabled by default to avoid unsafe configurations

This would be similar to how other reverse proxies and gateways handle real_ip_header / trusted_proxies.

Alternatives Considered

No response

Additional Context

No response