Skip to content

Commit 0de2f18

Browse files
ZPain8464kenjenkins
ZPain8464
and
kenjenkins
authoredJul 9, 2024··
Adds X-Forwarded-For settings page (#1488)
* first pass at updating these settings * updates reference file entries * updates redirects file * fixes breaking changes * runs prettier * fixes cspell issue * update XFF settings description and examples * update access log fields reference link --------- Co-authored-by: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com>
1 parent ffd914c commit 0de2f18

6 files changed

+207
-125
lines changed
 

‎content/docs/reference/access-log-fields.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -98,8 +98,8 @@ The table below lists all available access log fields:
9898
| :-- | :-- | :-- |
9999
| `authority` | The HTTP request `:authority` or `Host` header value. Can be a domain name or IP address and may contain a port number (for example, `www.example.com`) | Yes |
100100
| `duration` | The amount of time the request takes to complete in seconds | Yes |
101-
| `forwarded-for` | This is the value of the [`X-Forwarded-For`](/docs/reference/x-forwarded-for-http-header) header (as sent to the upstream service) | Yes |
102-
| `ip` | The user's IP address. Note that this depends on setting the [`xff_num_trusted_hops`](/docs/reference/the-number-of-trusted-hops) option appropriately. | No |
101+
| `forwarded-for` | The value of the `X-Forwarded-For` header, as sent to the upstream service (see also [X-Forwarded-For Settings](/docs/reference/x-forwarded-for-settings)) | Yes |
102+
| `ip` | The user's IP address. Note that this depends on setting the [`xff_num_trusted_hops`](/docs/reference/x-forwarded-for-settings#xff-number-of-trusted-hops) option appropriately. | No |
103103
| `method` | The HTTP request method, such as `GET`, `POST`, or `PUT` | Yes |
104104
| `path` | The HTTP request path (for example, `/some/path`) | Yes |
105105
| `referer` | The HTTP request referer, or the address of the web page from which the resource has been requested | Yes |

‎content/docs/reference/reference.json

+11-5
Original file line numberDiff line numberDiff line change
@@ -725,20 +725,26 @@
725725
},
726726
"x-forwarded-for-http-header": {
727727
"id": "x-forwarded-for-http-header",
728-
"title": "X-Forwarded-For HTTP Header",
729-
"path": "/x-forwarded-for-http-header",
730-
"description": "Indicates which IP addresses a request has flowed through between the client and upstream service.",
728+
"title": "Skip XFF Append",
729+
"path": "/x-forwarded-for-settings#skip-xff-append",
730+
"description": "Do not append client IP address to X-Forwarded-For header.",
731731
"services": [],
732732
"type": "bool"
733733
},
734734
"the-number-of-trusted-hops": {
735735
"id": "the-number-of-trusted-hops",
736-
"title": "The number of trusted hops",
737-
"path": "the-number-of-trusted-hops",
736+
"title": "XFF Number of Trusted Hops",
737+
"path": "/x-forwarded-for-settings#xff-number-of-trusted-hops",
738738
"description": "The number of trusted reverse proxies in front of pomerium.",
739739
"services": [],
740740
"type": "uint32"
741741
},
742+
"x-forwarded-for-settings": {
743+
"id": "x-forwarded-for-settings",
744+
"title": "X-Forwarded-For Settings",
745+
"path": "/x-forwarded-for-settings",
746+
"description": "Describes X-Forwarded-For settings and behavior."
747+
},
742748
"codec-type": {
743749
"id": "codec-type",
744750
"title": "Codec Type",

‎content/docs/reference/the-number-of-trusted-hops.mdx

-53
This file was deleted.

‎content/docs/reference/x-forwarded-for-http-header.mdx

-65
This file was deleted.

‎content/docs/reference/x-forwarded-for-settings.mdx

+190
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
---
2+
id: x-forwarded-for-settings
3+
title: X-Forwarded-For Settings
4+
description: This page documents X-Forwarded-HTTP header settings.
5+
keywords:
6+
- reference
7+
- X-Forwarded-For settings
8+
- x-forwarded-for-http-header
9+
- x forwarded for http header
10+
- the number of trusted hops
11+
- xff_num_trusted_hops
12+
- xff num trusted hops
13+
pagination_prev: null
14+
pagination_next: null
15+
toc_max_heading_level: 2
16+
---
17+
18+
import Tabs from '@theme/Tabs';
19+
import TabItem from '@theme/TabItem';
20+
21+
# X-Forwarded-For Settings
22+
23+
The `X-Forwarded-For` (XFF) HTTP header lists the IP addresses a request has passed through on its way from the end user (client) to a backend service.
24+
25+
(This is most relevant for deployments where there is another L7 proxy or load balancer in front of Pomerium, or in between Pomerium and upstream services.)
26+
27+
The following settings affect the way Pomerium sets or consumes the XFF header.
28+
29+
## Skip XFF Append
30+
31+
By default, when Pomerium receives a request, it appends the IP address of the direct downstream client to the XFF header before proxying the request to the upstream service.
32+
33+
However, if you set the **Skip XFF Append** (`skip_xff_append`) option to `true`, Pomerium will not modify an incoming XFF header. Instead, Pomerium will pass this incoming header to the upstream service unchanged.
34+
35+
### How to configure
36+
37+
<Tabs>
38+
<TabItem value="Core" label="Core">
39+
40+
| **Config file keys** | **Environment variables** | **Type** | **Default** |
41+
| :------------------- | :------------------------ | :-------- | :---------- |
42+
| `skip_xff_append` | `SKIP_XFF_APPEND` | `boolean` | `false` |
43+
44+
### Examples
45+
46+
```yaml
47+
skip_xff_append: true
48+
```
49+
50+
```bash
51+
SKIP_XFF_APPEND=true
52+
```
53+
54+
</TabItem>
55+
<TabItem value="Enterprise" label="Enterprise">
56+
57+
Configure **X-Forward-For HTTP Header** with the toggle button in the Console. The button has three states:
58+
59+
- **Unset** ("-") uses the value in your configuration file
60+
- **Checkmark** sets `skip_xff_append` to `true`
61+
- **Empty** sets `skip_xff_append` to `false`
62+
63+
![Configure x-forward-for-http-headers in the console](./img/headers/x-forwarded-for-http-header.png)
64+
65+
</TabItem>
66+
<TabItem value="Kubernetes" label="Kubernetes">
67+
68+
Kubernetes does not support `skip_xff_append`
69+
70+
</TabItem>
71+
</Tabs>
72+
73+
### Skip XFF Append examples
74+
75+
Assume you have a load balancer in front of Pomerium, and it connects to Pomerium from IP address `10.1.2.3`. Say that the load balancer is configured to populate the `X-Forwarded-For` header, so that if a client connects to the load balancer from IP address `192.0.5.1`, then the load balancer will set `X-Forwarded-For: 192.0.5.1` on the request to Pomerium.
76+
77+
With `skip_xff_append` set to `false` (the default behavior), Pomerium will then append the IP address of the load balancer on the request made to the upstream service:
78+
79+
```plain title="Request Details"
80+
X-Forwarded-For: 192.0.5.1,10.1.2.3
81+
```
82+
83+
With `skip_xff_append` set to `true`, Pomerium will not append the IP address of the load balancer on the request made to the upstream service:
84+
85+
```plain title="Request Details"
86+
X-Forwarded-For: 192.0.5.1
87+
```
88+
89+
## XFF Number of Trusted Hops
90+
91+
The **XFF Number of Trusted Hops** (`xff_num_trusted_hops`) setting instructs Pomerium whether to trust an incoming request's XFF header.
92+
93+
When unset or set to `0`, Pomerium will not trust the incoming XFF header. Pomerium will consider the client IP address to be the IP address of the direct downstream client.
94+
95+
This affects the client IP address logged in the access logs (if configured; see [Access log fields](/docs/reference/access-log-fields#access-log-fields-and-defaults)). The client IP address is also sent to the upstream service in the [`x-envoy-external-address` header](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-envoy-external-address).
96+
97+
:::info X-Forwarded-Proto header
98+
99+
This setting also affects whether Pomerium trusts the [`X-Forwarded-Proto` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto). This header indicates the originating protocol (either HTTP or HTTPS) of the downstream client request. Pomerium will only trust the downstream `X-Forwarded-Proto` header if you set `xff_num_trusted_hops` to a _non-zero_ value.
100+
101+
When set to `0`, Pomerium will set the `X-Forwarded-Proto` header to either `http` or `https` depending on whether the downstream connection is secured over TLS.
102+
103+
:::
104+
105+
### How to configure
106+
107+
<Tabs>
108+
<TabItem value="Core" label="Core">
109+
110+
| **Config file keys** | **Environment variables** | **Type** | **Usage** |
111+
| :--------------------- | :------------------------ | :------- | :----------- |
112+
| `xff_num_trusted_hops` | `XFF_NUM_TRUSTED_HOPS` | `uint32` | **optional** |
113+
114+
### Examples
115+
116+
```yaml
117+
xff_num_trusted_hops: 2
118+
```
119+
120+
```bash
121+
XFF_NUM_TRUSTED_HOPS=2
122+
```
123+
124+
</TabItem>
125+
<TabItem value="Enterprise" label="Enterprise">
126+
127+
`xff_num_trusted_hops` is a bootstrap configuration setting and is not configurable in the Console.
128+
129+
</TabItem>
130+
<TabItem value="Kubernetes" label="Kubernetes">
131+
132+
Kubernetes does not support `xff_num_trusted_hops`
133+
134+
</TabItem>
135+
</Tabs>
136+
137+
### XFF Number of Trusted Hops examples
138+
139+
As in the previous example, assume you have a load balancer in front of Pomerium, which connects to Pomerium from IP address `10.1.2.3`, and is configured to populate the `X-Forwarded-For` header.
140+
141+
With `xff_num_trusted_hops` set to `0`, Pomerium's access log will show the load balancer IP address (`10.1.2.3`) as the client IP address for all incoming requests.
142+
143+
```yaml {title="config.yaml"}
144+
xff_num_trusted_hops: 0
145+
access_log_fields: [forwarded-for, ip, method, path]
146+
```
147+
148+
Example access log entry:
149+
150+
```json
151+
{
152+
"level": "info",
153+
"service": "envoy",
154+
"forwarded-for": "192.0.5.1,10.1.2.3",
155+
"ip": "10.1.2.3",
156+
"method": "GET",
157+
"path": "/",
158+
"time": "2024-07-08T16:42:48-07:00",
159+
"message": "http-request"
160+
}
161+
```
162+
163+
With the `xff_num_trusted_hops` option set to `1`, Pomerium will trust the client IP address populated by the load balancer:
164+
165+
```yaml {title="config.yaml"}
166+
xff_num_trusted_hops: 1
167+
access_log_fields: [forwarded-for, ip, method, path]
168+
```
169+
170+
Example access log entry:
171+
172+
```json
173+
{
174+
"level": "info",
175+
"service": "envoy",
176+
"forwarded-for": "192.0.5.1,10.1.2.3",
177+
// highlight-next-line
178+
"ip": "192.0.5.1",
179+
"method": "GET",
180+
"path": "/",
181+
"time": "2024-07-08T16:42:48-07:00",
182+
"message": "http-request"
183+
}
184+
```
185+
186+
:::info Additional Resource
187+
188+
See the [**Envoy docs**](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers.html?highlight=skip_xff_append#x-forwarded-for) for more information about the `X-Forwarded-For` header.
189+
190+
:::

‎static/_redirects

+4
Original file line numberDiff line numberDiff line change
@@ -457,6 +457,10 @@ https://0-20-0.docs.pomerium.com/category/guides https://0-20-0.docs.pomerium.co
457457
# Pass Identity Headers
458458
/docs/reference/routes/pass-identity-headers /docs/reference/routes/pass-identity-headers-per-route
459459

460+
# X-Forwarded-For Settings
461+
/docs/reference/x-forwarded-for-http-header /docs/reference/x-forwarded-for-settings#skip-xff-append
462+
/docs/reference/the-number-of-trusted-hops /docs/reference/x-forwarded-for-settings#xff-number-of-trusted-hops
463+
460464
# Topics links - now concepts
461465
/docs/topics/auth-logs /docs/capabilities/audit-logs
462466
/docs/topics/single-sign-out.html /docs/capabilities/single-sign-out

0 commit comments

Comments
 (0)
Please sign in to comment.