Configuring XFCC Headers#

The page describes how to configure X-Forwarded-Client-Cert (XFCC) headers in Aspen Mesh.

Background#

XFCC is a proxy header which indicates certificate information of part or all of the clients or proxies that a request has flowed through, on its way from the client to the server.

Note

Your XFCC configuration should be set based on the trusted proxies deployed ahead of the Aspen Mesh ingress gateway.

A proxy may choose one of the following options prior to proxying the request.

  • Sanitize - Do not send the XFCC header to the next hop

  • Append - Append the immediate client’s certificate information to the request’s XFCC header and forward it to the next hop

  • Forward - Forward the XFCC header unmodified to the next hop

Note

The behavior of the XFCC header can only be modified for ingress gateway workloads

Aspen Mesh allows you to configure XFCC behavior only for ingress gateway workloads. By default, Aspen Mesh does not assume that the outside caller is a trusted entity so the XFCC header is SANITIZE_SET which resets the XFCC header to the immediate client’s certificate.

Note

When the proxy is deployed as a sidecar the Aspen Mesh XFCC configuration is set to APPEND_FORWARD. Sidecar proxies will add the client’s certificate to the XFCC header before sending the request to the next hop. There is no option to override or control this behavior.

Configuring Ingress Gateway XFCC Header#

To change the default behavior of the XFCC header for ingress gateway follow these steps.

Note

If you have an existing meshConfig settings in your overrides file you should merge these settings below.

  1. Add the following to the Aspen Mesh overrides.yaml file for your installation.

      meshConfig:
    defaultConfig:
      gatewayTopology:
        forwardClientCertDetails: <VALUE>

  2. Perform a clean installation or an upgrade of Aspen Mesh.

Configuration Options#

VALUE

Description

UNDEFINED

Field is not set.

SANITIZE

Do not send the XFCC header to the next hop. This is the default value for a gateway.

FORWARD_ONLY

When the client connection is mTLS (Mutual TLS), forward the XFCC header in the request.

APPEND_FORWARD

When the client connection is mTLS, append the client certificate information to the request’s XFCC header and forward it.

SANITIZE_SET

When the client connection is mTLS, reset the XFCC header with the client certificate information and send it to the next hop.

ALWAYS_FORWARD_ONLY

Always forward the XFCC header in the request, regardless of whether the client connection is mTLS.

XFCC Header Details#

An XFCC header may contain information about multiple certificates so the following are true when understanding the format of the header value

  • XFCC header value is a comma “,” separated string of XFCC elements

  • XFCC elements hold information added by each proxy the request has passed through

  • XFCC elements are semicolonn “;” separated strings

  • Each substring of an XFCC element is a key value pair grouped together by an equal sign “=”

  • The keys of an XFCC element are case-insensitive

  • The values of an XFCC elementa are case-sensitive

XFCC Keys#

The following keys are supported in an XFCC element

Key

Description

By

The Subject Alternative Name (URI type) of the current proxy’s certificate.

Hash

The SHA 256 digest of the current client certificate.

Cert

The entire client certificate in URL encoded PEM format.

Chain

The entire client certificate chain (including the leaf certificate) in URL encoded PEM format.

Subject

The Subject field of the current client certificate. The value is always double-quoted.

URI

The URI type Subject Alternative Name field of the current client certificate.

DNS

The DNS type Subject Alternative Name field of the current client certificate. A client certificate may contain multiple DNS type Subject Alternative Names, each will be a separate key-value pair.

XFCC Header Examples#

{
  "headers": {
  "Accept": "*/*",
  "Content-Length": "0",
  "Host": "httpbin.httpbin:8000",
  "<snipped>": "...",
  "X-Forwarded-Client-Cert": "By=spiffe://cluster.local/ns/httpbin/sa/httpbin;Hash=7b2fc54ce2f52be7eda46aa967183674cc203220fd4ea05909f80c206fcca12f;Subject=\"\";URI=spiffe://cluster.local/ns/httpbin/sa/sleep"
}

Reference#