Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 39 ยท JWT and OAuth2 Resource Server

JWT Structure: Header, Payload and Signature

Learn how a JSON Web Token is built: header, claims payload and signature, Base64URL encoding, registered claims and why a JWT is signed but not secret.

A session cookie is a random string that points at data stored on the server. A JSON Web Token (JWT, pronounced "jot") works the other way around: the token itself carries the data, and a signature proves nobody changed it. That makes JWTs popular for APIs, mobile apps and services that must verify a caller without calling a shared session store.

This lesson takes a JWT apart piece by piece. The real Spring Security classes (JwtDecoder, NimbusJwtDecoder, JwtEncoder) come in the next lessons. The Spring Security libraries cannot run on this site, so every runnable example here is a plain Java stand-in built from the JDK only. It shows the same ideas that the framework implements for you: never use these hand-written helpers in production, use a vetted library.

The three parts

A JWT is three Base64URL strings joined by dots:

TEXT
xxxxx.yyyyy.zzzzz
header.payload.signature
Part Contains Example
Header Token type and signing algorithm {"alg":"HS256","typ":"JWT"}
Payload Claims: statements about the user and the token {"sub":"alice","exp":1760000000}
Signature A MAC or digital signature over header.payload 32 bytes for HS256

Three parts, two dots

Header alg and typ
Payload The claims
Signature Proves integrity

Each part is Base64URL text

1 / 3

Base64URL is an encoding, not a lock

Base64URL turns bytes into text that is safe in URLs and headers: it uses - and _ instead of + and /, and drops the = padding. Anyone can reverse it. Run the next program and read what is "hidden" inside a token.

Java Build a token by hand

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The signature is 32 bytes for HMAC-SHA256, which is 43 Base64URL characters. The decoded payload is readable by everyone who sees the token, so never put passwords, card numbers or other secrets in a JWT. If the content must be hidden you need an encrypted token (JWE), which is rarely what an API needs.

Registered claims

The payload is a JSON object. A few claim names are standardized (RFC 7519) and Spring Security knows them by name:

Claim Meaning Checked by Spring?
iss Issuer: who created the token Yes, if you configure an issuer URI
sub Subject: who the token is about (a stable user id) Becomes Authentication.getName()
aud Audience: who the token is meant for Only if you add a validator
exp Expiration time, seconds since 1970 Yes, always
nbf Not before Yes, always
iat Issued at Informational
jti Unique token id Useful for revocation lists

Anything else is a custom claim: roles, tenant, email, scope. Keep them small, because the token travels in an Authorization header on every request.

Reading claims without a JSON library

Real code uses Jackson or Nimbus. To keep the stand-in dependency-free, the next program uses a tiny parser that handles flat string and number fields. It shows the shape of what a decoder returns: a header map and a claims map.

Java Decode and inspect a token

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that this program never checked the signature. Decoding is not validating. A server that reads claims before verifying the signature trusts data an attacker may have written. The next lesson adds verification.

JWT versus session ID

Session cookie JWT in Authorization header
Where state lives Server Inside the token
Revoke on logout Delete the session Hard: needs a denylist or short life
Scales across servers Needs shared store or sticky sessions Any server with the key can verify
Size Small (a random id) Hundreds of bytes
Typical use Server-rendered web apps APIs, mobile apps, service-to-service

Neither is "more secure" by nature. A JWT in localStorage can be stolen by an XSS bug; a session cookie needs CSRF protection (see CSRF protection). Pick by architecture, not fashion.

Keep access tokens short-lived (5 to 15 minutes) so a stolen token stops working quickly. Long sessions come from refresh tokens, covered in Refresh tokens and revocation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement about the payload of a signed JWT is true?

    Base64URL is a reversible encoding. The signature protects integrity, not confidentiality.
  2. 2. Which claim holds the expiration time?

    exp is the expiration time in seconds since the Unix epoch. iat is the issue time, sub the subject and jti the token id.
  3. 3. Why is decoding a token not enough before trusting it?

    Anyone can craft a header and payload. Only verifying the signature with the right key shows the issuer created them.
  4. 4. What are the three parts of a JWT, in order?

    The format is header.payload.signature, and the signature covers the first two parts.

Summary

  • A JWT is header.payload.signature, each part Base64URL text.
  • The payload holds claims such as iss, sub, aud, exp and your own custom claims.
  • A signed JWT is tamper-evident but readable: never store secrets in it.
  • Decode and validate are different steps: always verify the signature first.
  • Prefer short-lived tokens and keep claims small.

Next: Signing and validating JWTs