IP address plays fundamental role in HTTP; it's used for access control, auditing, geo-based access analysis and more.
Echo provides handy method
Context#RealIP() for that.
However, it is not trivial to retrieve the real IP address from requests especially when you put L7 proxies before the application. In such situation, real IP needs to be relayed on HTTP layer from proxies to your app, but you must not trust HTTP headers unconditionally. Otherwise you might give someone a chance of deceiving you. A security risk!
To retrieve IP address reliably/securely, you must let your application be aware of the entire architecture of your infrastructrure.
In Echo, this can be done by configuring
This guides show you why and how.
Note: if you don't set
Echo#IPExtractor explicitly, Echo fallback to legacy behavior, which is not a good choice.
Let's start from two questions to know the right direction:
- Do you put any HTTP (L7) proxy in front of the application?
- It includes both cloud solutions (such as AWS ALB or GCP HTTP LB) and OSS ones (such as Nginx, Envoy or Istio ingress gateway).
- If yes, what HTTP header do your proxies use to pass client IP to the application?
Case 1. With no proxy
If you put no proxy (e.g.: directory facing to the internet), all you need to (and have to) see is IP address from network layer. Any HTTP header is untrustable because the clients have full control what headers to be set.
In this case, use
e.IPExtractor = echo.ExtractIPDirect()
Case 2. With proxies using X-Forwarded-For header
X-Forwared-For (XFF) is the popular header to relay clients' IP addresses.
At each hop on the proxies, they append the request IP address at the end of the header.
Following example diagram illustrates this behavior.
┌──────────┐ ┌──────────┐ ┌──────────┐
───────────>│ Proxy 1 │───────────>│ Proxy 2 │───────────>│ Your app │
│ (IP: b) │ │ (IP: c) │ │ │
└──────────┘ └──────────┘ └──────────┘
XFF: "" "a" "a, b"
XFF: "x" "x, a" "x, a, b"
↑ What your app will see
In this case, use first untrustable IP reading from right. Never use first one reading from left, as it is configurable by client. Here "trustable" means "you are sure the IP address belongs to your infrastructure". In above example, if
c are trustable, the IP address of the client is
a for both cases, never be
In Echo, use
e.IPExtractor = echo.ExtractIPFromXFFHeader()
e.IPExtractor = echo.ExtractIPFromXFFHeader(
echo.TrustLoopback(false), // e.g. ipv4 start with 127.
echo.TrustLinkLocal(false), // e.g. ipv4 start with 169.254
echo.TrustPrivateNet(false), // e.g. ipv4 start with 10. or 192.168
Case 3. With proxies using X-Real-IP header
X-Real-IP is another HTTP header to relay clients' IP addresses, but it carries only one address unlike XFF.
If your proxies set this header, use
e.IPExtractor = echo.ExtractIPFromRealIPHeader()
Never forget to configure the outermost proxy (i.e.; at the edge of your infrastructure) not to pass through incoming headers. Otherwise there is a chance of fraud, as it is what clients can control.
About default behavior
In default behavior, Echo sees all of first XFF header, X-Real-IP header and IP from network layer.
As you might already notice, after reading this article, this is not good. Sole reason this is default is just backward compatibility.