Back to blog

Websecurity • Authentication • JWT

JSON Web Token (JWT): In-Depth Overview

4 min read

A JSON Web Token (JWT) is essentially a compact, URL-safe data structure used to securely transmit information between two parties.

It consists of three parts, which are concatenated together using dots (.) to form the final token string:

JWT=Header.Payload.Signature\text{JWT} = \text{Header} . \text{Payload} . \text{Signature}

JWT Anatomy

The Header (JOSÉ)

The Header, formally known as the JSON Object Signing and Encryption (JOSÉ) Header, is a JSON object that contains metadata about the token itself.

Claim KeyExample ValueDescription
typ"JWT"Type: Indicates the object is a JSON Web Token.
alg"HS256"Algorithm: Specifies the cryptographic algorithm used to sign the token (e.g., HMAC using SHA-256).

The Payload (Claims)

The Payload, known as the Claims Set, is a JSON object that contains the actual data (claims or assertions) about the subject (usually the user) and other token properties.

Claim KeyExample ValueDescription
sub"user@example.com"Subject: The principal the token is about (usually the user ID or email).
exp1764355200Expiration Time: A timestamp indicating when the token must no longer be accepted.
iat1764268800Issued At: The timestamp when the token was created.
role"ADMIN"A custom claim used by the application to hold user roles.

The Signature (The Seal)

The Signature is the security guarantee of the JWT. It ensures the token hasn't been tampered with and verifies that the token was genuinely issued by the server.

  • Process: The signature is created by taking the encoded Header, the encoded Payload, and a Secret Key (known only to the server) and feeding all three into the cryptographic algorithm specified in the Header (e.g., HS256).
Signature=HS256(encodedHeader+"."+encodedPayload,SecretKey)\text{Signature} = \text{HS256}(\text{encodedHeader} + "." + \text{encodedPayload}, \text{SecretKey})
Json Web Token (JWT) Structure
Json Web Token (JWT) Structure

JWT Workflow

Established connection
We assume an encrypted HTTPS connection has been established between the client and the server, typically utilizing a Diffie-Hellman key exchange.
login/signup process
Client signs up with email/password, server validates, hashes, and stores it; on login the server compares the submitted password to the stored hash to authenticate.
creating digital signtaure
The server creates a Digital Signature. This signature can also be generated using asymmetric keys (public/private key pair) for enhanced security in distributed systems.
JWT sent to the client
From now on for every authenticated API call, the client need to attache the recieved JWT in the header (Authorization: Bearer <token>).
JWT verification
When the client sends a request with a JWT, the server recomputes the signature using the request payload and its secret. If the signature matches, the token is valid and untampered.

digital signature

A digital signature is a cryptographic proof that a message came from the claimed sender, wasn’t altered, and can’t later be denied. The sender hashes the data, signs that hash with their private key, and anyone with their public key can verify the authenticity, integrity, and non-repudiation of the message.

RS256

In a larger microservices setup you’ll usually switch to asymmetric keys:

  • Signing: The auth service hashes the payload and encrypts that hash with its private key; the output becomes the signature.
  • Verification: Any other service uses the public key to decrypt the signature, recovers the original hash, and compares it to the hash it computed locally. If the hashes match, the token is trusted.

Further exploring