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