CertificateThumbprintFilter

Extracts a Java certificate from a trusted header or from a TLS connection, computes the SHA-256 thumbprint of that certificate, and makes the thumbprint available for the ConfirmationKeyVerifierAccessTokenResolver. Use this filter to enable verification of certificate-bound access tokens.

CertificateThumbprintFilter computes and makes available the SHA-256 thumbprint of a client certificate as follows:

Evaluates a runtime expression and yields a java.security.cert.Certificate
Hashes the certificate using SHA-256
Base64url-encodes the result
Stores the result in the contexts chain

The runtime expression can access or build a client certificate from any information present at runtime, such as a PEM in a header, or a pre-built certificate.

Use CertificateThumbprintFilter with ConfirmationKeyVerifierAccessTokenResolver when the PingGateway instance is behind the TLS termination point, for example, when PingGateway is running behind a load balancer or other ingress point.

Usage

{
  "name": string,
  "type": "CertificateThumbprintFilter",
  "config": {
    "certificate": runtime expression<certificate>,
    "failureHandler": Handler reference,
  }
}

Properties

"certificate": runtime expression<certificate>, required

An EL expression which, when evaluated, yields an instance of a java.security.cert.Certificate.

Use the following Functions in the expression to define the hash, decoding, and certificate:

digestSha256, to calculate the SHA-256 hash of the certificate.
decodeBase64url, to decode an incoming base64url-encoded string.
derCertificate, to convert a base64-encoded DER-format string into a certificate.
pemCertificate, to convert a PEM-format string into a certificate.

Refer to Examples.

"failureHandler": Handler reference, optional: Handler to treat the request on failure.

Provide an inline handler configuration object or the name of a handler object declared in the heap. See also Handlers.

Default: HTTP 403 Forbidden, the request stops being executed.

Examples

Certificate from HTTPS

When PingGateway terminates TLS, use the certificate associated with the incoming HTTPS connection:

{
  "name": "CertificateThumbprintFilter-1",
  "type": "CertificateThumbprintFilter",
  "config": {
    "certificate": "${contexts.client.certificates[0]}"
  }
}

From an NGINX trusted header

When NINGX fronts PingGateway and terminates TLS, it can send the client certificate in a trusted header.

The following example uses x-ssl-cert as the trusted header. NGINX encodes the certificate in PEM format and URL-encodes the result:

{
  "name": "CertificateThumbprintFilter-2",
  "type": "CertificateThumbprintFilter",
  "config": {
    "certificate": "${pemCertificate(urlDecode(request.headers['x-ssl-cert'][0]))}"
  }
}

For details, refer to the NGINX Module ngx_http_ssl_module documentation.

From an Envoy or Istio trusted header

When Envoy or Istio fronts PingGateway and terminates TLS, it can send the client certificate in a field in a trusted header.

The following example uses x-forwarded-client-cert as the trusted header. Envoy puts the client certificate in the Cert field of the header value. Envoy encodes the certificate in PEM format and URL-encodes the result:

{
  "name": "CertificateThumbprintFilter-3",
  "type": "CertificateThumbprintFilter",
  "config": {
    "certificate": "${pemCertificate(urlDecode(findGroups(request.headers['x-forwarded-client-cert'][0], 'Cert=([^;]+);?')[1]))}"
  }
}

For details, refer to the Envoy x-forwarded-client-cert documentation.

More information

org.forgerock.openig.filter.oauth2.cnf.CertificateThumbprintFilter

PingGateway 2024.11