Skip to main content

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

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.

Examples​

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

Pass dynamic tokens in headers​

The following token substitutions are available:

TokenValue
${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 $$.

danger

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.

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}

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

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

YAML/JSON settingTypeUsage
set_response_headersstringoptional

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.

Set Authorization Header​

caution

As of v0.23.0, set_authorization_header has been deprecated in favor of set_request_headers and will be removed in v0.24.0.

Now, set_request_headers allows you to include ID and Access tokens in requests so you don't have to designate the Authorization header to send these values.

Set Authorization Header allows you to send a user's identity token through as a bearer token in the Authorization header.

How to configure​

YAML/JSON settingTypeDefaultUsage
set_authorization_headerstringpass_throughoptional

Options​

OptionDefinition
access_tokenSend the OAuth access token
id_tokenSend the OIDC ID token
pass_throughLeave the Authorization header unchanged from the client when it's not used for Pomerium authentication

Examples​

set_authorization_header: pass_through