Headers Settings
This reference covers all of Pomerium's Headers Settings:
Host Rewrite
The Host Rewrite setting preserves the Host header with the preserve_host_header
setting. You can customize the Host Rewrite setting with the following options:
How to configure
- Core
- Enterprise
- Kubernetes
YAML/JSON settings | Type | Usage |
---|---|---|
host_rewrite | string | optional |
host_rewrite_header | string | optional |
host_path_regex_rewrite_pattern | string | optional |
host_path_regex_rewrite_substitution | string | optional |
Examples
host_rewrite: 'example.com'
Configure Host Rewrite settings in the route Headers settings in the Console:
Annotation name | Type | Usage |
---|---|---|
host_rewrite | string | optional |
Examples
ingress.pomerium.io/host_rewrite: 'example.com'
Host Rewrite options
1. Preserve Host Header
preserve_host_header
passes the Host header from the incoming request to the proxied host, instead of the destination hostname. It's an optional parameter of type boolean
that defaults to false
.
See ProxyPreserveHost.
2. Host Rewrite
host_rewrite
rewrites the Host to a new literal value.
3. Host Rewrite Header
host_rewrite_header
rewrites the Host to match an incoming header value.
4. Host Path Regex Rewrite Pattern/Substitution
host_path_regex_rewrite_pattern
and host_path_regex_rewrite_substitution
rewrite the Host according to a regex matching the path. For example:
host_path_regex_rewrite_pattern: '^/(.+)/.+$'
host_path_regex_rewrite_substitution: \1
This configuration would rewrite the Host header to example.com
given the path /example.com/some/path
.
The 2nd, 3rd, and 4th options correspond to the Envoy route action host related options.
Set Request Headers
Set Request Headers allows you to set both static and dynamic values for given request headers. Static values can be useful if you want to pass along additional information to upstream applications as headers, or to set a fixed authentication header on the request.
The dynamic values enable you to pass ID and Access tokens from your identity provider to upstream applications.
To pass dynamic values from the user's OIDC claim to an upstream service, see JWT Claim Headers.
Neither HTTP/2 pseudo-headers (for example, :authority
) nor the Host:
header may be modified via this mechanism. Those headers may instead be modified via prefix_rewrite
, regex_rewrite
, and host_rewrite
.
How to configure
- Core
- Enterprise
- Kubernetes
YAML/JSON setting | Type | Usage |
---|---|---|
set_request_headers | map of key-value pairs | optional |
Examples
Pass static header values in the request:
- from: https://verify.corp.example.com
to: https://verify.pomerium.com
policy:
- allow:
or:
- email:
is: user@example.com
set_request_headers:
# Set a fixed Basic Auth username and password (root:hunter42)
Authorization: Basic cm9vdDpodW50ZXI0Mg==
# Set a custom header
X-Your-favorite-authenticating-Proxy: 'Pomerium'
# To include a '$' character in a header value:
X-Hello: $$world # header value is set to "$world"
Pass ID token, access token, and client certificate fingerprint (if present) as dynamic headers in the request:
- from: https://verify.corp.example.com
to: https://verify.pomerium.com
policy:
- allow:
or:
- email:
is: user@example.com
set_request_headers:
x-pomerium-idp-id-token: ${pomerium.id_token}
x-pomerium-idp-access-token: ${pomerium.access_token}
x-pomerium-client-cert-fingerprint: ${pomerium.client_cert_fingerprint}
Configure Set Request Headers in the Console:
Annotation name | Type | Usage |
---|---|---|
set_request_headers | map of key-value pairs | optional |
ingress.pomerium.io/set_request_headers: |
X-Test: X-Value
Pass dynamic tokens in headers
The following token substitutions are available:
Token | Value |
---|---|
${pomerium.id_token} | OIDC ID token from the identity provider* |
${pomerium.access_token} | OAuth access token from the identity provider* |
${pomerium.client_cert_fingerprint} | Short form SHA-256 fingerprint of the presented client certificate (if downstream mTLS is enabled) |
*The ID token and access token are not available when using the Hosted Authenticate service.
Note: Token values must use the ${pomerium.<token>}
syntax. To include a literal $
character in a header value, use $$
.
Be very careful when passing access tokens to an upstream application. This may allow the application to make other authenticated requests on behalf of the user.
Remove Request Headers
Remove Request Headers allows you to remove given request headers. This can be useful if you want to prevent privacy information from being passed to downstream applications.
How to configure
- Core
- Enterprise
- Kubernetes
YAML/JSON setting | Type | Usage |
---|---|---|
remove_request_headers | string | optional |
Examples
- from: https://verify.corp.example.com
to: https://verify.pomerium.com
policy:
- allow:
or:
- email:
is: user@example.com
remove_request_headers:
- X-Email
- X-Username
Set Remove Request Headers in the Console:
Annotation name | Type | Usage |
---|---|---|
remove_request_headers | string | optional |
ingress.pomerium.io/remove_request_headers: |
- X-Email
- X-User
Set Response Headers
Set Response Headers allows you to set static values for the given response headers. These headers will take precedence over the global set_response_headers
.
How to configure
- Core
- Enterprise
- Kubernetes
YAML/JSON setting | Type | Usage |
---|---|---|
set_response_headers | string | optional |
Examples
set_response_headers:
X-Test: X-Value
Configure Set Response Headers in the Console:
Annotation name | Type | Usage |
---|---|---|
set_response_headers | string | optional |
ingress.pomerium.io/set_response_headers: |
X-Test: X-Value
Rewrite Response Headers
Rewrite Response Headers allows you to modify response headers before they are returned to the client. The header
field will match the HTTP header name, and prefix
will be replaced with value
.
How to configure
- Core
- Enterprise
- Kubernetes
YAML/JSON setting | Type | Usage |
---|---|---|
rewrite_response_headers | object | optional |
Examples
If the downstream server returns a header:
Location: http://localhost:8000/two/some/path/
And the policy has this config:
rewrite_response_headers:
- header: Location
prefix: http://localhost:8000/two/
value: http://frontend/one/
The browser would be redirected to: http://frontend/one/some/path/
. This is similar to nginx's proxy_redirect
option, but can be used for any header.
Configure Rewrite Response Headers in the Console:
Annotation name | Type | Usage |
---|---|---|
rewrite_response_headers | object | optional |
Examples
If the downstream server returns a header:
Location: http://localhost:8000/two/some/path/
And the Ingress object has this annotation:
ingress.pomerium.io/rewrite_response_headers: |
- header: Location
prefix: http://localhost:8000/two/
value: http://frontend/one/
The browser would be redirected to: http://frontend/one/some/path/
. This is similar to nginx's proxy_redirect
option, but can be used for any header.