Fixing proxy headers

If you are serving Hypercorn behind a proxy e.g. a load balancer the client-address, scheme, and host-header will match that of the connection between the proxy and Hypercorn rather than the user-agent (client). However, most proxies provide headers with the original user-agent (client) values which can be used to “fix” the headers to these values.

Modern proxies should provide this information via a Forwarded header from RFC 7239. However, this is rare in practice with legacy proxies using a combination of X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host. It is important that you chose the correct mode (legacy, or modern) based on the proxy you use.

To use the proxy fix middleware behind a single legacy proxy simply wrap your app and serve the wrapped app,

from hypercorn.middleware import ProxyFixMiddleware

fixed_app = ProxyFixMiddleware(app, mode="legacy", trusted_hops=1)

Warning

The mode and number of trusted hops must match your setup or the user-agent (client) may be trusted and hence able to set alternative for, proto, and host values. This can, depending on your usage in the app, lead to security vulnerabilities.

The trusted_hops argument should be set to the number of proxies that are chained in front of Hypercorn. You should set this to how many proxies are setting the headers so the middleware knows what to trust.