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:

NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs

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();
System.out.println(thumbprintURI);

Example JWK thumbprint URI:

urn:ietf:params:oauth:jwk-thumbprint:sha-256:NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs

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 {
    ThumbprintURI.parse("urn:...");
} catch (ParseException e) {
    // Illegal thumbprint URI
    System.err.println(e.getMessage());
}

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)
    .keyIDFromThumbprint()
    .build();

Example RSA JWK with a thumbprint-based identifier:

{
  "kty" : "RSA",
  "n"   : "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx4cbbfAAt
           VT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMstn6
           4tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FD
           W2QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n9
           1CbOpbISD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINH
           aQ-G_xBniIqbw0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
  "e"   : "AQAB",
  "alg" : "RS256",
  "kid" : "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
}