JWT Decode vs Verify

JWT decoding vs verification at a glance

A compact signed JWT is normally a JSON Web Signature object with three dot-separated segments. The first two segments are designed to be readable. Their visibility is not a weakness and it is not encryption. The third segment provides integrity only when a consumer verifies it correctly. The comparison below keeps syntax, cryptography, and policy separate.

The JWT Best Current Practices in RFC 8725 describes failures that occur when applications blur these stages. Its central themes are algorithm verification, key strength, input validation, issuer and audience checks, explicit typing where needed, and mutually exclusive validation rules for token kinds that could otherwise be confused.

What a JWT decoder reads

For compact JWS, the token has this outer form:

BASE64URL(UTF8(JOSE header))
.
BASE64URL(UTF8(JWT Claims Set))
.
BASE64URL(JWS signature bytes)

The JOSE header is a JSON object. It normally contains an alg parameter naming the cryptographic algorithm. It may contain typ, kid, certificate-related parameters, or extension parameters. Every one is input from the token. A secure implementation does not let that input broaden its configured algorithm or key policy.

The Claims Set is another JSON object. Registered names include iss for issuer, sub for subject, aud for audience, exp for expiration, nbf for not-before, iat for issued-at, and jti for a token identifier. Private claims can describe application-specific roles, scopes, tenants, sessions, or other data. They are assertions until the token is verified and its issuer is trusted for those meanings.

The signature segment is binary data represented with Base64URL. Turning it into hex or measuring its length is still decoding, not verification. A random byte string can occupy the segment and look structurally plausible. Verification recomputes or checks the cryptographic value using the exact protected header segment, a dot, and the exact payload segment as transmitted.

Base64URL is not encryption or authentication

Base64URL is the URL-safe alphabet defined by RFC 4648. It substitutes - and _ for the standard alphabet’s + and /. Compact JOSE representations omit padding. The transformation is reversible and has no key. A person, browser extension, proxy log, or script that receives the token can normally read a signed JWT’s header and payload.

This has two practical consequences. First, do not put confidential data in an ordinary signed JWT merely because the string looks opaque. Second, never use successful Base64URL decoding as an authentication decision. It checks the encoding layer. Strict decoding should still reject wrong alphabets, padding, whitespace, impossible lengths, invalid UTF-8, malformed JSON, non-object Claims Sets, and ambiguous duplicate names.

RFC 7797 defines a JWS option that can leave a payload unencoded, but Section 7 states that JWTs must not use that option. A JWT decoder can therefore reject a protected b64:false header instead of guessing how to parse the middle segment.

What correct JWS verification requires

Cryptographic verification is not a call to “decode with a secret.” It is a policy-guided operation over the original JWS signing input. A robust implementation needs all of the following:

1. A preconfigured algorithm allowlist. The application decides which algorithms are acceptable for this token type. The untrusted alg header selects only within that set; it does not expand it.
2. The correct cryptographic operation. HMAC algorithms use a shared secret. RSA and elliptic-curve algorithms use a private key to sign and a public key to verify. Substituting one key kind or operation for another creates algorithm-confusion risk.
3. A trusted key source. Keys come from application configuration or a controlled discovery process tied to the expected issuer. A decoded jku, x5u, or kid value is not authority to read arbitrary URLs, files, database rows, or object properties.
4. Adequate key strength and lifecycle. Weak HMAC secrets can be guessed offline. Public keys need trusted distribution and rotation. Retired or compromised keys need an explicit rejection and revocation strategy.
5. Exact signing input. Verification covers the original encoded protected header, dot, and encoded payload. Parsing and reserializing first is not equivalent.
6. Failure-closed behavior. Unknown algorithms, keys, critical parameters, malformed signatures, invalid encodings, duplicate policy claims, and verification errors all produce rejection, not a best-effort decoded result.

A good JOSE library can implement the primitive correctly, but the caller still owns configuration. Passing the token’s algorithm directly into a generic crypto API, using one byte string for both HMAC and public-key modes, or accepting every algorithm supported by a library weakens that boundary.

Why algorithm and key confusion matter

RFC 8725 records several classes of attacks that affected real JWT deployments. Understanding them explains why “signature present” and even “crypto function returned true” are not enough without policy.

The unsecured alg:none case

JOSE defines an unsecured JWS form whose algorithm is none and whose signature segment is empty. That format is not secretly broken; it is explicitly unsecured. The failure occurs when an application expecting signed access tokens accepts it. A decoder should label it clearly. A verifier for an authenticated token contract should reject it because none is absent from the allowlist.

HMAC versus public-key confusion

An application may expect an RSA-signed token and possess the issuer’s public key. If a vulnerable implementation lets the token switch to an HMAC algorithm and then uses those public-key bytes as an HMAC secret, an attacker who knows the public key can produce a matching MAC. The defense is not to inspect the algorithm after the fact; it is to bind each token type and key to a fixed compatible algorithm policy.

Weak symmetric keys

An HMAC signature can be tested offline against candidate secrets. A human password, short environment value, repository placeholder, or shared default may be recoverable even when the HMAC algorithm itself is sound. Generate keys with sufficient entropy, protect them as credentials, rotate them, and avoid using one key across unrelated environments or token types.

Key lookup injection

A kid helps select among trusted keys; it is not a filename, SQL fragment, object path, or remote URL. Likewise, remote-key header parameters need strict trust and network policy. Treat every header value as untrusted data, constrain its format, and select only from the expected issuer’s controlled key set.

Verification is followed by claim validation

A cryptographically valid signature establishes integrity under a key. It does not tell the consumer why that key signed the token, which service should accept it, or whether its assertions fit the current request. Claim validation converts cryptographic evidence into an application acceptance decision.

Audience deserves particular attention. RFC 7519 permits either one case-sensitive string or an array of strings. A general JSON parser that assumes only one form can reject legitimate tokens or, worse, skip the comparison. Issuer and audience rules should be exact and bound to the same token configuration that selected the keys and algorithms.

Expiration checks are necessary but not sufficient

The exp claim is an exclusive upper boundary: the current time must be before it. At equality, it has expired. The nbf claim is an inclusive lower boundary: the current time must be at or after it. Implementations may permit a small leeway for clock skew, but the value should be explicit rather than hidden in a decoder.

NumericDate uses seconds since the Unix epoch and may be fractional. JavaScript wall-clock APIs commonly return milliseconds, so unit confusion is a frequent bug. Floating-point conversion can also change very large or highly precise number text. A diagnostic tool can use exact arithmetic, but a production verifier should follow the maintained library’s supported NumericDate range and reject unsupported types rather than coercing strings or nulls.

Checking exp in an unverified payload is useful for debugging only. An attacker can put any future number into a new payload. The application must verify the signature before accepting the claim, and it may still enforce a shorter maximum age, session revocation, key rotation, or replay rules. Use the JWT Expiration Checker to inspect boundaries while keeping that distinction visible.

A safe JWT validation pipeline

Exact library calls vary, but the order of decisions can remain stable. A useful review model is:

policy = configuration.forTokenType("access-token")

token = parseCompactJwsWithLimits(input)
require token.protectedHeader.alg in policy.allowedAlgorithms
require token.protectedHeader.typ == policy.requiredType

key = policy.trustedKeys.select(token.protectedHeader.kid)
require key.algorithmCompatibleWith(token.protectedHeader.alg)
require verifyOriginalJwsSigningInput(token, key)

claims = token.requireUniqueJsonObjectClaims()
require claims.iss == policy.expectedIssuer
require policy.expectedAudience in normalizeAudience(claims.aud)
require now < claims.exp + policy.clockSkew
require now >= claims.nbf - policy.clockSkew  // when present
require replayPolicy.accepts(claims.jti, claims.iat)

identity = mapVerifiedSubject(claims.sub)
authorize(identity, request.action, request.resource)

The sequence validates protected structure and policy before trusting claims. Some libraries combine parsing and signature verification in one safe call; use their intended API instead of reproducing low-level JOSE operations. The important review questions remain: Which algorithms are allowed? Where do keys come from? Which issuer and audience are required? Which claims are mandatory? Which time and replay policy is applied? What exact token type can this endpoint accept?

Duplicate names, JSON behavior, and ambiguity

RFC 7519 requires the names in a Claims Set to be unique, while also describing parser behavior in terms of ECMAScript’s last-name-wins behavior or rejection. Security-sensitive systems should avoid a state where one component reads the first aud or exp and another reads the last. Rejecting duplicates before policy evaluation removes that disagreement.

Escapes make duplicate detection more subtle. The JSON names "exp" and "\u0065xp" decode to the same string. Comparing raw token slices is insufficient; the parser needs to compare decoded property names while preserving enough source information to report the ambiguity. The same concern applies to duplicate alg or b64 header parameters.

Do not convert the claims object into a language dictionary that invokes setters or prototype behavior for names such as __proto__. A hardened parser or maintained JOSE library should treat property names as inert data, enforce size and nesting limits, and escape all diagnostic rendering. These are input-validation properties, separate from the cryptographic primitive.

Signed JWT, nested JWT, and encrypted JWE

A signed compact JWS has three segments. Compact JWE has five: protected header, encrypted key, initialization vector, ciphertext, and authentication tag. Segment count alone does not validate that an arbitrary five-part string is a JWE, but a properly formed compact JWE does not expose a readable JWT Claims Set because the content is encrypted. It needs complete format validation, recipient-key selection, algorithm policy, authenticated decryption, and content-type handling.

Applications can nest the formats. One design signs a JWT and then encrypts the signed result; another order has different security and interoperability properties. The consumer must know the expected nesting and validate every layer with separate rules. A three-part decoder should not join or skip JWE segments to make the input look readable.

Encryption hides content from parties without the recipient key, while a signature or MAC protects integrity and origin under its key model. Neither automatically creates authorization. If claims are sensitive, consider whether they belong in a client-carried token at all, how logs and error reports handle the compact value, and whether server-side session state offers a smaller exposure surface.

A safer JWT debugging workflow

• Prefer a synthetic development token. Reproduce the same claim shape without a production bearer credential.
• Decode locally for inspection. Check segment syntax, exact JSON, claim types, duplicate names, time units, and expected header labels.
• Keep the verification status explicit. Screenshots and copied reports should say that the signature was not checked.
• Reproduce verification in the actual service. Use its configured issuer, key set, algorithm allowlist, audience, clock, and token type.
• Log reasons, not secrets. Record a safe token fingerprint, key ID, issuer classification, and failure category rather than the compact token or personal claims.
• Test exact boundaries. Cover before, equal to, and after exp/nbf, as well as key rotation, unknown kid, wrong audience, and algorithm mismatch.
• Clear incidental copies. Clipboard managers, shell history, browser storage, tickets, chat, and recordings can outlive the token’s original context.