---
title: CertificateThumbprintFilter
description: Configure CertificateThumbprintFilter to compute a client certificate SHA-256 thumbprint and enable certificate-bound access token verification
component: pinggateway
version: 2026
page_id: pinggateway:reference:CertificateThumbprintFilter
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/CertificateThumbprintFilter.html
revdate: 2025-06-02T18:01:47Z
section_ids:
  CertificateThumbprintFilter-usage: Usage
  CertificateThumbprintFilter-properties: Properties
  CertificateThumbprintFilter-examples: Examples
  certificate_from_https: Certificate from HTTPS
  from_an_nginx_trusted_header: From an NGINX trusted header
  from_an_envoy_or_istio_trusted_header: From an Envoy or Istio trusted header
  CertificateThumbprintFilter-moreinfo: More information
---

# 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

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

## Properties

* `"certificate"`: *runtime expression<[certificate](preface.html#definition-certificate)>, required*

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

  Use the following [PingGateway functions](Functions.html) 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](#CertificateThumbprintFilter-examples).

- `"failureHandler"`: *Handler [reference](preface.html#definition-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](Handlers.html).

  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:

```json
{
  "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:

```json
{
  "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](https://nginx.org/en/docs/http/ngx_http_ssl_module.html#variables) 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:

```json
{
  "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](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert) documentation.

## More information

[org.forgerock.openig.filter.oauth2.cnf.CertificateThumbprintFilter](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/cnf/CertificateThumbprintFilter.html)