spring-projects/spring-security · error · OAuth2AuthenticationException
server_error
server_error
Error message
Failed to compute SHA-256 Thumbprint for client X509Certificate.
What it means
For TLS client authentication (tls_client_auth or self_signed_tls_client_auth) with x509-certificate-bound access tokens, the JWT access token customizer computes the RFC 8705 SHA-256 thumbprint (x5t#S256) of the client's X509Certificate to bind the token to it. This RuntimeException fires when the thumbprint computation fails — e.g. the certificate is null/missing from the client authentication, or the certificate encoding cannot be digested — so the token cannot be issued with the required certificate binding.
Source
Thrown at config/src/main/java/org/springframework/security/config/annotation/web/configurers/oauth2/server/authorization/DefaultOAuth2TokenCustomizers.java:88
if (OAuth2TokenType.ACCESS_TOKEN.equals(tokenContext.getTokenType())
&& tokenContext.getAuthorizationGrant() != null && tokenContext.getAuthorizationGrant()
.getPrincipal() instanceof OAuth2ClientAuthenticationToken clientAuthentication) {
if ((ClientAuthenticationMethod.TLS_CLIENT_AUTH.equals(clientAuthentication.getClientAuthenticationMethod())
|| ClientAuthenticationMethod.SELF_SIGNED_TLS_CLIENT_AUTH
.equals(clientAuthentication.getClientAuthenticationMethod()))
&& tokenContext.getRegisteredClient().getTokenSettings().isX509CertificateBoundAccessTokens()) {
X509Certificate[] clientCertificateChain = (X509Certificate[]) clientAuthentication.getCredentials();
try {
String sha256Thumbprint = computeSHA256Thumbprint(clientCertificateChain[0]);
cnfClaims = new HashMap<>();
cnfClaims.put("x5t#S256", sha256Thumbprint);
}
catch (Exception ex) {
OAuth2Error error = new OAuth2Error(OAuth2ErrorCodes.SERVER_ERROR,
"Failed to compute SHA-256 Thumbprint for client X509Certificate.", null);
throw new OAuth2AuthenticationException(error, ex);
}
}
}
// Add 'cnf' claim for OAuth 2.0 Demonstrating Proof of Possession (DPoP)
Jwt dPoPProofJwt = tokenContext.get(OAuth2TokenContext.DPOP_PROOF_KEY);
if (OAuth2TokenType.ACCESS_TOKEN.equals(tokenContext.getTokenType()) && dPoPProofJwt != null) {
JWK jwk = null;
@SuppressWarnings("unchecked")
Map<String, Object> jwkJson = (Map<String, Object>) dPoPProofJwt.getHeaders().get("jwk");
try {
jwk = JWK.parse(jwkJson);
}
catch (Exception ignored) {
}
if (jwk == null) {
OAuth2Error error = new OAuth2Error(OAuth2ErrorCodes.INVALID_DPOP_PROOF,
"jwk header is missing or invalid.", null);View on GitHub (pinned to 96852e8860)
Solutions
- Ensure the OAuth2ClientAuthenticationToken carries a valid client X509Certificate for the TLS client authentication method
- Verify the certificate is PEM/DER encodable and not corrupted
- Check that isX509CertificateBoundAccessTokens is only enabled for registrations that actually use certificate-bound tokens
- Confirm the JCA SHA-256 MessageDigest provider is available in the runtime
Defensive patterns
Strategy: validation
When it happens
Trigger: Thrown at config/src/main/java/org/springframework/security/config/annotation/web/configurers/oauth2/server/authorization/DefaultOAuth2TokenCustomizers.java:88 when the library encounters an invalid state.
Common situations: See trigger scenarios.
Understand the failure class
- SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10).
Data as JSON: /api/errors/e930ffb08c3623f1.
Report an issue: GitHub.