CR HeaderRewrites

Airlock Microgateway offers predefined header lists and header filtering/rewriting configuration options. With these built-in options, request and response headers can be added to or removed from upstream and downstream traffic (see Reference tables of built-in header lists). The predefined header lists are constantly evolving and updated to respond to latest threats and new requirements.

Custom header rewrite rules can be defined to address various integration requirements.
These mechanisms can prevent information leakage by response headers and attacks by request headers.

In the Custom Resource HeaderRewrites, all header-related actions can be configured. The content of the CR is split into two main sections request and response.

General tips for working with CRs

  • CLI:
  • Use kubectl explain <replace with CRD name> --recursive to list all available options and the YAML structure.
  • Check the CRD description texts with kubectl explain <replace with CRD name and path> of the available options for more details.
  • API Reference documentation:
  • Click on the link to open the CR-related documentation in a new browser tab or window: CRD Reference documentation. See also the API Reference documentation links at the end article.

Example configuration

copy
apiVersion: microgateway.airlock.com/v1alpha1 
kind: HeaderRewrites 
metadata: 
  name: my-header-rewrites 
spec: 
  request: 
    allow: 
      matchingHeaders: 
        custom: 
          - name: Allow X-CSRF-Token header
            headers: 
              - name: 
                  matcher: 
                    exact: X-CSRF-TOKEN 
    remove: 
      custom: 
      - name: Remove X-Forwarded-Host
        headers: 
        - name: 
            matcher: 
              exact: X-Forwarded-Host
    add: 
      custom: 
        - name: Add headers with TLS information of the downstream connection 
          headers: 
            - name: X-TLS-DOWNSTREAM-PEER-CERT 
              value: "%DOWNSTREAM_PEER_CERT%" 
            - name: X-TLS-DOWNSTREAM-PEER-CERT-V-START 
              value: "%DOWNSTREAM_PEER_CERT_V_START%" 
            - name: X-TLS-DOWNSTREAM-PEER-CERT-V-END 
              value: "%DOWNSTREAM_PEER_CERT_V_END%" 
          mode: OverwriteOrAdd 
  response: 
    allow: 
      ...
    remove: 
      builtIn: 
        auth: 
          basic: true  
    add: 
      custom: 
        - name: Add application version as header 
          headers: 
            - name: X-APP-VERSION 
              value: "3.7.4" 
          mode: OverwriteOrAdd

See also the API Reference documentation link at the end of this article.

Custom rules

Depending on the configured action such as allow, remove or add, custom rules can be configured using different matcher settings.

Example:

copy
apiVersion: microgateway.airlock.com/v1alpha1 
kind: HeaderRewrites 
metadata: 
  name: my-header-rewrites
spec:  
  request:  
    allow: 
      matchingHeaders: 
        custom: 
          - name: Allow X-CSRF-Token header from web application 
            headers: 
              - name: 
                  matcher: 
                    exact: X-CSRF-TOKEN 
    remove:  
      custom:  
      - name: Remove X-Forwarded-Host 
        headers:  
        - name:  
            matcher:  
              exact: X-Forwarded-Host 
    add: 
      custom: 
        - name: Add headers with TLS information of the downstream connection 
          headers: 
            - name: X-TLS-DOWNSTREAM-PEER-CERT 
              value: "%DOWNSTREAM_PEER_CERT%" 
          mode: OverwriteOrAdd

All custom rules must be configured with a name and/or value parameter to identify the header.

Only one of the matcher options can be set per rule, i.e. exact or regex except for the header value ignoreCase option, which can be added as an addition to allow and remove rules. See CRD description texts for more details.

Configured action

Additional information

allow

  • Allows custom header rules.

    • It is possible to disable filtering based on header allow sections using the allHeaders: {} option. In this case, you should use an equivalent set of remove rules to avoid unwanted information leakage through response headers or attacks through request headers.

remove

  • The configuration options for custom rules in the remove section are similar to those in the allow section.

add

  • To add a header with the given name and value. In addition, a mode parameter can be added to define the behavior in case the header is already existing.

    • By default, it is set to AddIfAbsent but could be set to OverwriteOrAdd.

See also the API Reference documentation link at the end of this article.

Processing order of header actions

  1. Request/response headers are processed in the following order:
  2. Remove all headers, that are not explicitly listed in a built-in or a custom allow rule.
  3. Remove all headers, that are explicitly listed in a built-in or a custom remove rule.
  4. Add all headers, that are listed in a built-in or custom add rule.

Access log output

Header rewrite actions are not displayed in the access log by default. For header rewrite logging, the operationalMode must be set to Integration.

See Integration mode for CR HeaderRewrites for detailed instructions.

See also the API Reference documentation link at the end of this article.

Reference in CR ContentSecurity

The CR HeaderRewrites need to be referenced in the CR ContentSecurity.

...
spec: 
  filter: 
  headerRewritesRef: 
    name: my-header-rewrites
...

Replace the name: in our example with the actual name from the metadata section of the respective HeaderRewrites CR.

See also the API Reference documentation link at the end of this article.