quarkusio/quarkus · error · org.jose4j.keys.resolvers.UnresolvableKeyException

JWK with the certificate thumbprint '%s' is not available

Error message

JWK with the certificate thumbprint '%s' is not available

What it means

Thrown by OidcProvider's JsonWebKeyResolver.resolveKey when the token has no 'kid' and no 'x5t#S256', but carries the legacy 'x5t' (SHA-1 certificate thumbprint) header, and no JWK matches that thumbprint. As with the other thumbprint branch, when only 'x5t' is set the exact key must exist; otherwise UnresolvableKeyException is thrown.

Source

Thrown at extensions/oidc/runtime/src/main/java/io/quarkus/oidc/runtime/OidcProvider.java:577

            if (key == null) {
                thumbprint = jws.getHeader(HeaderParameterNames.X509_CERTIFICATE_SHA256_THUMBPRINT);
                if (thumbprint != null) {
                    key = getKeyWithS256Thumbprint(thumbprint);
                    if (key == null) {
                        // if only `x5tS256` was set then the key must exist
                        throw new UnresolvableKeyException(
                                String.format("JWK with the SHA256 certificate thumbprint '%s' is not available", thumbprint));
                    }
                }
            }

            if (key == null) {
                thumbprint = jws.getHeader(HeaderParameterNames.X509_CERTIFICATE_THUMBPRINT);
                if (thumbprint != null) {
                    key = getKeyWithThumbprint(thumbprint);
                    if (key == null) {
                        // if only `x5t` was set then the key must exist
                        throw new UnresolvableKeyException(
                                String.format("JWK with the certificate thumbprint '%s' is not available", thumbprint));
                    }
                }
            }

            if (key == null && kid == null && thumbprint == null) {
                try {
                    key = jwks.getKeyWithoutKeyIdAndThumbprint(jws.getKeyType());
                } catch (InvalidAlgorithmException ex) {
                    LOG.debug("Token 'alg'(algorithm) header value is invalid", ex);
                }
            }

            if (key == null && oidcConfig.jwks().tryAll() && kid == null && thumbprint == null) {
                LOG.debug("JWK is not available, neither 'kid' nor 'x5t#S256' nor 'x5t' token headers are set,"
                        + " falling back to trying all available keys");
                key = jwks.findKeyInAllKeys(jws);
            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Confirm the SHA-1 thumbprint of the JWKS entry's x5c certificate equals the token's 'x5t' value
2. Refresh the cached JWKS after provider certificate rotation
3. Ask the issuer to sign with 'kid' or 'x5t#S256' headers, which Quarkus prefers
4. Pin the signing certificate locally via quarkus.oidc.token.certificate-chain if the provider's JWKS is unreliable

Example fix

// token x5t (SHA-1) 'XyZ...' mismatched with republished cert
// after: refresh JWKS or pin:
quarkus.oidc.token.certificate-chain=...

try {
    return validate(token);
} catch (AuthenticationFailedException e) {
    if (String.valueOf(e.getCause()).contains("certificate thumbprint")) {
        // try local pinned cert or request JWKS refresh
        return verifyWithPinnedCert(token);
    }
    throw e;
}

When it happens

Trigger: Verifying a JWT whose header contains 'x5t' (SHA-1 thumbprint, no 'kid', no 'x5t#S256') while getKeyWithThumbprint(thumbprint) returns null against the tenant's key set.

Common situations: Older identity providers or Java-based signers that emit SHA-1 'x5t' while the JWKS exposes x5c entries whose SHA-1 thumbprint doesn't match (wrong cert in chain); tokens cross-issued between environments; provider republished certs after rotation without the app refreshing JWKS.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• JWK with the SHA256 certificate thumbprint '%s' is not avail
• %s type can not be used to represent JWT claims in @Singleto
• Thumprint of the root chain certificate is invalid
• Thumprint of the leaf chain certificate is invalid
• Invalid certificate chain

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/2a7611ece9e3d7f9. Report an issue: GitHub.