{"record":{"id":"1f95857d8f8b68d8","repo":"quarkusio/quarkus","slug":"jwk-with-the-sha256-certificate-thumbprint-s-is","errorCode":null,"errorMessage":"JWK with the SHA256 certificate thumbprint '%s' is not available","messagePattern":"JWK with the SHA256 certificate thumbprint '(.+?)' is not available","errorType":"exception","errorClass":"org.jose4j.keys.resolvers.UnresolvableKeyException","httpStatus":401,"severity":"error","filePath":"extensions/oidc/runtime/src/main/java/io/quarkus/oidc/runtime/OidcProvider.java","lineNumber":565,"sourceCode":"\n            // Try 'kid' first\n            String kid = jws.getKeyIdHeaderValue();\n            if (kid != null) {\n                key = getKeyWithId(kid);\n                if (key == null) {\n                    // if `kid` was set then the key must exist\n                    throw new UnresolvableKeyException(String.format(\"JWK with kid '%s' is not available\", kid));\n                }\n            }\n\n            String thumbprint = null;\n            if (key == null) {\n                thumbprint = jws.getHeader(HeaderParameterNames.X509_CERTIFICATE_SHA256_THUMBPRINT);\n                if (thumbprint != null) {\n                    key = getKeyWithS256Thumbprint(thumbprint);\n                    if (key == null) {\n                        // if only `x5tS256` was set then the key must exist\n                        throw new UnresolvableKeyException(\n                                String.format(\"JWK with the SHA256 certificate thumbprint '%s' is not available\", thumbprint));\n                    }\n                }\n            }\n\n            if (key == null) {\n                thumbprint = jws.getHeader(HeaderParameterNames.X509_CERTIFICATE_THUMBPRINT);\n                if (thumbprint != null) {\n                    key = getKeyWithThumbprint(thumbprint);\n                    if (key == null) {\n                        // if only `x5t` was set then the key must exist\n                        throw new UnresolvableKeyException(\n                                String.format(\"JWK with the certificate thumbprint '%s' is not available\", thumbprint));\n                    }\n                }\n            }\n\n            if (key == null && kid == null && thumbprint == null) {","sourceCodeStart":547,"sourceCodeEnd":583,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/oidc/runtime/src/main/java/io/quarkus/oidc/runtime/OidcProvider.java#L547-L583","documentation":"Thrown by OidcProvider's JsonWebKeyResolver.resolveKey when the token has no usable 'kid' but declares an 'x5t#S256' (SHA-256 X.509 certificate thumbprint) header, and no JWK in the key set matches that thumbprint. Since only 'x5tS256' was set, the resolver must find the exact key and cannot fall back, so it fails fast with UnresolvableKeyException.","triggerScenarios":"Verifying a JWT whose header contains 'x5t#S256' (and no 'kid') while getKeyWithS256Thumbprint(thumbprint) returns null against the tenant's key set.","commonSituations":"Token issuer embeds its cert thumbprint in the header but the JWKS entry lacks the x5c chain needed to compute S256 thumbprints (only RSA modulus/exponent exposed); x509 thumbprint algorithm mismatch between issuer and JWKS; tokens issued by a different provider than configured.","solutions":["Verify the JWK set contains an x5c certificate whose SHA-256 thumbprint matches the token header; ask the issuer to publish full certificate chains","Check the token really came from the configured tenant's JWKS endpoint","If the token has neither matching kid nor thumbprint, configure the expected signing key statically (quarkus.oidc.token.public-key / certificate-chain)","Refresh JWKS in case keys rotated since the cache was filled"],"exampleFix":"// token x5tS256: 'AbCd...' not matched because JWKS publishes only n/e\n// after: issuer publishes x5c, or app pins the key:\nquarkus.oidc.token.certificate-chain=... // pin the leaf cert","handlingStrategy":"fallback","validationCode":"// check token header has x5t#S256 and JWKS exposes x5c certs before verifying\nif (header.getX509CertSHA256Thumbprint() != null && jwksKeys.stream().noneMatch(k -> k.getX509CertificateChain() != null)) {\n    throw new IllegalStateException(\"Token uses x5t#S256 but JWKS has no x5c certificates\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    return validate(token);\n} catch (AuthenticationFailedException e) {\n    if (String.valueOf(e.getCause()).contains(\"SHA256 certificate thumbprint\")) {\n        return refreshJwksAndRetry(token);\n    }\n    throw e;\n}","preventionTips":["Ask issuers to publish full x5c chains in JWKS","Prefer providers that sign with 'kid' or 'x5t#S256' rather than SHA-1 'x5t'","Refresh JWKS after any provider certificate rotation"],"tags":["jwt","oidc","x509","thumbprint"],"backgroundTag":"jwk-thumbprint-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}