Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Security and hardening

JJWT rejects a token because the signature does not match

ErrorSignatureException thrown while parsing a signed JWT

Short answer

JJWT recomputes the signature with the key you give the parser. A SignatureException means that key differs from the one used to sign: the secret was decoded another way, the wrong secret is configured, or an RSA token was verified with the wrong key. Build the key the same way on both sides.

  • Applies to JJWT 0.12 and 0.13, Java 21
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print how the signing side and the verifying side each derive their key, from the same configuration value. Also read the alg field in the token header (decode the first part of the token).

    grep -rn "hmacShaKeyFor\|verifyWith\|signWith" src/
  2. 2Match what you see, then jump to its fix

    1. 1Tokens from your own service fail in your own serviceThe secret is decoded differently when signing and verifyingFix
    2. 2Tokens issued by another service (RS256 or ES256 in the header) failAn asymmetric token is checked with the wrong keyFix
    3. 3A short secret in an environment fileThe key is shorter than the algorithm needsFix

What does the error look like?

  • SignatureException thrown while parsing a signed JWT
  • Login works but every request with the issued token is rejected

Cause 1 of 3

The secret is decoded differently when signing and verifying

1Check

One side passes raw bytes of the secret string, the other Base64-decodes it, or one uses Base64URL. These produce different keys from the same text.

grep -rn "getBytes\|Decoders\." src/

2Fix

Pick one format and use it in both places. JJWT's documented way to turn an encoded secret into a key is Keys.hmacShaKeyFor with the matching decoder.

SecretKey key = Keys.hmacShaKeyFor(Decoders.BASE64.decode(secretString));

3Verify

Sign a token with the key and parse it back in a unit test.

String jws = Jwts.builder().subject("Joe").signWith(key).compact();
Jwts.parser().verifyWith(key).build().parseSignedClaims(jws);

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

An asymmetric token is checked with the wrong key

1Check

Read the alg value of the token header. For RSA or EC algorithms the token is signed with a private key and must be verified with the matching public key. JJWT 0.12 no longer accepts a private key for verification.

grep -rn "verifyWith" src/

2Fix

Load the issuer's public key and pass it to verifyWith.

Jwts.parser()
    .verifyWith(publicKey)   // java.security.PublicKey
    .build()
    .parseSignedClaims(token);

3Verify

Parse a token from that issuer.

./mvnw -q test

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

The key is shorter than the algorithm needs

1Check

JJWT states that HS256 requires a secret key at least 32 bytes long.

printf %s "$JWT_SECRET" | wc -c

2Fix

Generate a key of the right size with the algorithm's key builder, store it Base64-encoded, and use that value in every environment.

SecretKey key = Jwts.SIG.HS256.key().build();
String secretString = Encoders.BASE64.encode(key.getEncoded());

3Verify

Decode the stored string with Decoders.BASE64 and run the sign-then-parse round trip.

./mvnw -q test

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Keep one small helper class that builds the key; both signing and parsing call it.
  • Store secrets Base64-encoded and say so in the variable name, for example JWT_SECRET_B64.
  • Add a sign-then-parse unit test that runs in CI.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Security

Users see the unverified app warning on Google sign-in

Sign-in is blocked for accounts that are not on the test user list

Google shows the unverified app screen when an app requests sensitive or restricted scopes without approved verification.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.