JWT Decoder

Anatomy of a JSON Web Token

A JWT is a compact, self-contained credential defined by RFC 7519. It is three Base64URL encoded segments joined by dots, and the format is designed so that a receiver can validate and read it without a database lookup. Nothing in it is encrypted: the first two segments are plain JSON wearing a very thin disguise.

• Header. Metadata about the token itself, principally alg (the signing algorithm) and typ (normally JWT). It may also carry kid, a key identifier telling the verifier which key to use.
• Payload. The claims, a JSON object of statements about the subject plus whatever the application needs.
• Signature. A cryptographic value computed over the first two segments and a key. It proves the token has not been altered.

Worked Example: Splitting a Token

Take the token above and decode each segment independently. Note that the signature is raw bytes, not text, so decoding it produces unreadable output. That is expected.

The segments use Base64URL, so dash stands in for plus, underscore for slash, and the trailing equals padding is stripped. That is why pasting a segment into a strict standard Base64 decoder sometimes fails on length.

Registered Claims

Seven claim names are registered by the specification. Everything else is either a public claim from the IANA registry or a private claim agreed between the issuer and consumer, such as email, scope, roles, or tenant_id.

All three time claims are seconds since the Unix epoch, not milliseconds. Converting them in JavaScript requires multiplying by 1000 before constructing a Date, and forgetting that produces expiry dates in 1970.

HS256 vs RS256

The alg header names the algorithm used to produce the signature. Two dominate real deployments, and the difference is about who needs to hold which key.

• HS256 (HMAC with SHA-256). Symmetric. One shared secret both signs and verifies. Fast and simple, but every service that verifies a token can also mint one, so it suits a single application that issues tokens to itself.
• RS256 (RSA signature with SHA-256). Asymmetric. A private key signs, a widely published public key verifies. Verifiers can never forge tokens, which is what makes it the standard choice for identity providers, OpenID Connect, and any multi-service architecture. ES256 offers the same property using elliptic curves with much smaller keys.

A verifier must decide which algorithm it accepts before it looks at the token, never after. Trusting the alg field in the header is the root of a well known class of attacks.

JWT Security Essentials

• Never put secrets in the payload. It is encoded, not encrypted. Anyone holding the token can read every claim.
• Always verify the signature server-side with a key you configured, not one derived from the token.
• Reject alg set to none. The specification allows an unsecured token, and libraries that honoured it turned forgery into a one line attack.
• Pin the expected algorithm. If you expect RS256, do not let a token arrive claiming HS256 and trick the verifier into using your public key as an HMAC secret.
• Always check exp, and nbf when present. Allow only a small clock skew, measured in seconds.
• Validate iss and aud. A valid token issued for a different service is not a valid token for yours.
• Keep lifetimes short. A JWT cannot be revoked by itself, so an access token should live for minutes and be refreshed, not for days.