Skip to main content

Headers Settings

This reference covers all of Pomerium's Headers Settings:

Host Header Settings​

By default, Pomerium will set the Host header of an upstream request according to the host specified in the To URL for the route.

(Strictly speaking, the Host header is used only with HTTP/1.1. For HTTP/2 and HTTP/3 the :authority pseudo-header is used instead. These settings affect both identically.)

You can change how Pomerium sets this header using the following settings:

1. Preserve Host Header​

preserve_host_header passes the Host header from the incoming request to the upstream service, instead of the host from the route's To URL.

This is like the Apache httpd ProxyPreserveHost directive.

2. Host Rewrite​

host_rewrite rewrites the Host header to a fixed value.

3. Host Rewrite Header​

host_rewrite_header rewrites the Host header using the value of some other header from the incoming request. For example:

host_rewrite_header: X-My-Host

For an incoming request with the header X-My-Host: foo.example.com, this would rewrite the Host header to foo.example.com.

4. Host Path Regex Rewrite Pattern/Substitution​

host_path_regex_rewrite_pattern and host_path_regex_rewrite_substitution rewrite the Host header based on a regular expression substitution using the URL path as the input. For example:

host_path_regex_rewrite_pattern: '^/(.+)/.+$'
host_path_regex_rewrite_substitution: \1

For a request URL with the path /example.com/some/path, this would rewrite the Host header to example.com.

How to configure​

YAML/JSON settingsTypeUsage
preserve_host_headerbooleanoptional
host_rewritestringoptional
host_rewrite_headerstringoptional
host_path_regex_rewrite_patternstringoptional
host_path_regex_rewrite_substitutionstringoptional

Examples​

preserve_host_header: true
host_rewrite: 'example.com'

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.

caution

Neither HTTP/2 pseudo-headers (for example, :authority) nor the Host header may be modified via this mechanism. The request path may instead be modified using the Path Rewriting Settings and the Host header may be modified using the Host Header Settings above.

How to configure​

YAML/JSON settingTypeUsage
set_request_headersmap of key-value pairsoptional

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}

Pass dynamic tokens in headers​

The following token substitutions are available:

TokenValue
${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)
${pomerium.id_token}OIDC ID token from the identity provider*
${pomerium.jwt}Pomerium JWT (this is the same value as in the X-Pomerium-Jwt-Assertion header)

*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 $$.

warning

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​

YAML/JSON settingTypeUsage
remove_request_headersstringoptional

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 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​

YAML/JSON settingTypeUsage
set_response_headersstringoptional

Examples​

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​

YAML/JSON settingTypeUsage
rewrite_response_headersobjectoptional

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.