JSON Web Key (JWK) thumbprints

JWK thumbprints are secure hashes for uniquely identifying key material. Their computation is specified in RFC 7638.

How to compute a JWK thumbprint

The library can compute thumbprints for all supported JWK types - RSA, EC, octet key pair (OKP) and and octet sequence (symmetric keys). The default hash algorithm is SHA-256, but other digest algorithms can also be used provided they the underlying JCA provider can handle them.

To compute the SHA-256 thumbprint of an RSA key:

RSAKey rsaKey = RSAKey.parse("{ ... }");
Base64URL thumbprint = rsaKey.computeThumbprint();

The thumbprints are returned as a base64-url safe string.

Example JWK thumbprint:


To compute the thumbprint using another hash algorithm use the alternative computeThumbprint(String) method which expects a string designating the digest:

RSAKey rsaKey = RSAKey.parse("{ ... }");
Base64URL thumbprint = rsaKey.computeThumbprint("SHA-1");

How to compute a JWK thumbprint URI

A JWK thumbprint URI (RFC 9278) is a special URI with the urn:ietf:params:oauth:jwk-thumbprint prefix intended to represent thumbprints as URNs.

RSAKey rsaKey = RSAKey.parse("{ ... }");

# Compute the SHA-256 thumbprint and represent as URI
ThumbprintURI thumbprintURI = rsaKey.computeThumbprintURI();

Example JWK thumbprint URI:


The ThumbprintURI class has a static method that can also compute SHA-256 thumbprint URIs:

JWK jwk = JWK.parse("{ ... }");
ThumbprintURI thumbprintURI = rsaKey.computeThumbprintURI();

To parse a thumbprint URI:

try {
} catch (ParseException e) {
    // Illegal thumbprint URI

How to use JWK thumbprints as key identifiers

A JWK thumbprint can be used as a natural key identifier for the kid (key ID) JWK parameter, instead of an UUID, an incremented integer or some other identifier scheme. Key identifiers have use in JWK sets, to facilitate key identification and roll-over.

To set the SHA-256 thumbprint as the key ID:

RSAKey rsaKey = new RSAKey.Builder(mod, exp)

Example RSA JWK with a thumbprint-based identifier:

  "kty" : "RSA",
  "n"   : "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt
  "e"   : "AQAB",
  "alg" : "RS256",
  "kid" : "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"