A JSON Web Token (JWT) is a compact, URL-safe format for carrying claims—statements represented as a JSON object. A JWT may be signed or protected with a message authentication code (MAC), encrypted, or both. The common readable, signed form protects integrity but does not hide its contents: anyone who obtains it may be able to read its claims.
What does a JWT contain?
A claim is a name-and-value statement, such as who issued a token, which subject it concerns, or when it expires. The JWT standard defines registered claim names including iss (issuer), sub (subject), aud (audience), exp (expiration time), nbf (not-before time), iat (issued-at time), and jti (token identifier). These are defined names, not a checklist that every JWT must contain. An application or protocol determines which claims it requires and how to interpret them. See the IETF’s RFC 7519.
As an Amazon Associate I earn from qualifying purchases.
How is a JWT structured?
JWT is a claims format, and its compact representation depends on the protection being used. The familiar three-part token is a compact JWS: it has a protected header, a payload, and a signature or MAC, separated by dots.
Recommended Free Tools
- Protected header: metadata about the cryptographic operation, including an algorithm identifier.
- Payload: the claims, represented as JSON.
- Signature or MAC: cryptographic data used to check integrity and, depending on the scheme and key, the token’s origin.
For illustration only, a three-part token has this shape: encoded-header.encoded-payload.signature. This is a schematic, not a usable token. The header and payload are commonly Base64url-encoded JSON; Base64url encoding is a transport-friendly representation, not encryption.
#1 Best Overall
Does a JWT keep its contents secret?
Not necessarily. In a signed JWS, the signature or MAC helps detect changes, but the payload is not thereby made confidential. If a token is exposed, its readable claims may be exposed too. Do not put secrets in a signed-only JWT on the assumption that its signature hides them.
A compact JWE is the encrypted JWT form and has five dot-separated parts rather than the three parts of a compact JWS. Encryption is used to provide confidentiality. Some constructions nest signing and encryption to combine protections. The IETF describes these formats in RFC 7519 and its security guidance in RFC 8725.
JWS and JWE: what is the difference?
| Representation | Typical compact form | Protection |
|---|---|---|
| JWS | Three dot-separated parts | Signs or MACs the content to support integrity and origin validation; does not, by itself, make claims confidential. |
| JWE | Five dot-separated parts | Encrypts the content to provide confidentiality. |
A nested construction can combine signing and encryption. Which form is appropriate depends on the application’s protocol and security requirements; the format alone does not establish that a token is safe to use.
Why decoding a JWT is not validation
Decoding only reveals how encoded parts are represented. It does not prove that a token was issued by a trusted party, has not been altered, is intended for this application, or is currently valid. An application must verify the cryptographic protection with the correct key and then check the claims and purpose it expects.
Rank #3
- Use an explicit allowlist of supported algorithms, and ensure the algorithm in the header matches the cryptographic operation the application actually performs.
- Verify the signature or MAC with the appropriate trusted key before relying on claims.
- Check the expected issuer and audience, applicable time limits such as expiration and not-before, and any application-specific requirements.
- Do not blindly fetch a key from a URL named in an untrusted token header; RFC 8725 warns that doing so can create server-side request forgery risk.
These are security principles, not framework-specific setup instructions. RFC 8725, the IETF’s JWT Best Current Practice published in February 2020, discusses implementation and deployment risks including unexpected algorithm acceptance. Its recommendations may be updated; check the applicable standard and errata for the system you are building.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
