Skip to main content
Version: vNext (upcoming release)

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​

YAML/JSON settingsTypeUsage
host_rewritestringoptional
host_rewrite_headerstringoptional
host_path_regex_rewrite_patternstringoptional
host_path_regex_rewrite_substitutionstringoptional

Examples​

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.

caution

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​

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.