JWT Signature Verifier
Verify an HS256 JWT against an exact UTF-8 secret without treating signature validity as claim acceptance.
Interpreted as exact UTF-8 text. Base64 or Base64URL-looking text is not decoded first.
Verification Result
A matching signature is not an authorization decision
Signature verification proves that the encoded header and payload match the supplied key. The application still has to validate time claims, issuer, audience, token type, permissions, revocation and its own acceptance rules.
Matching the MAC is only the first gate
HS256 is HMAC with SHA-256. The signer and verifier share the same secret, and the MAC covers the exact compact-JWS signing input: the protected header segment, a dot, and the payload segment. Change one encoded character and the expected MAC changes.
Before cryptography runs, the token is checked as a JWT rather than arbitrary JWS text: three non-empty compact sections, canonical unpadded Base64URL, strict UTF-8 JSON objects for the protected header and claims set, and an alg value of exactly HS256.
Why the exact secret bytes matter
The secret field is encoded as UTF-8 exactly as entered. If another library first decodes a Base64 or Base64URL key string into bytes, pasting that encoded text here describes a different HMAC key and verification will fail even when the visible characters look familiar.
RFC 7518 requires an HS256 key at least 256 bits in size. A 32-byte string reaches that length threshold, but a predictable phrase can still have poor entropy. JWT Best Current Practices specifically warns about weak, human-memorable symmetric keys because a captured token can be used for offline guessing.
Critical extensions are stopped rather than guessed
A JWS crit header says that listed extensions must be understood before the signature can be safely processed. Unknown critical extensions are therefore rejected instead of ignored. The unencoded-payload b64=false extension is also rejected because it changes the JWS signing input and does not fit the normal compact JWT form handled here.
After a signature matches
Evaluate exp and nbf against the application's clock-skew policy. iat can be useful context but is not an expiry rule by itself.
Validate iss and aud against values configured by the relying application, not values learned from the token itself.
An access token, ID token and session token can carry overlapping claims but have different acceptance rules and should not be interchangeable.
Roles, scopes, revocation, account state and endpoint authorization remain application decisions after cryptographic verification.
Why verification can fail even when the token looks normal
- The shared secret differs by one character, space, line break or text encoding.
- The application stores key bytes as decoded Base64 while the visible configuration contains the encoded form.
- The protected header names another algorithm or uses a critical extension.
- The compact segments contain padding, malformed Base64URL or non-canonical trailing bits.
- The payload or protected header is not valid UTF-8 JSON for a JWT.
- The signature was computed over a different header or payload than the token now contains.
Standards behind the result
RFC 7519 defines JWT, RFC 7515 defines JWS compact signing input, and RFC 7518 defines HS256 and its key-size requirement. RFC 8725 is the current best-practice reference for avoiding weak symmetric keys and algorithm confusion.
RFC 7519 — JSON Web Token·RFC 7515 — JSON Web Signature·RFC 7518 — JSON Web Algorithms·RFC 8725 — JWT Best Current Practices