JSON Web Token (JWT)
A JSON Web Token (JWT) is a compact, URL-safe standard (RFC 7519) for creating self-contained access tokens that assert a number of claims. Because all necessary information is in the token itself, JWTs allow for stateless, scalable authentication systems, making them a cornerstone of modern token-based authentication.
Structure of a JWT
A JWT consists of three parts separated by dots (.): a Header, a Payload, and a Signature.
xxxxx.yyyyy.zzzzz
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
1. Header
The header is a JSON object that declares the token type (typ) and the signing algorithm (alg) used, such as [[hashing-algorithms|HS256]] (HMAC using SHA-256) or RS256 (RSA). This JSON is then Base64Url encoded to form the first part of the JWT.
Example Header (JSON):
{
"alg": "HS256",
"typ": "JWT"
}2. Payload
The payload is a JSON object containing the claims, which are statements about an entity (typically the user) and additional metadata. Like the header, the payload is Base64Url encoded to form the second part of the JWT.
Types of Claims:
- Registered Claims: A standard set of predefined claims, such as
iss(issuer),exp(expiration time),sub(subject/user ID), andiat(issued at). These are recommended but not mandatory. - Public Claims: Custom claims defined by the application. To avoid collisions, they should be defined in the IANA JSON Web Token Registry or as a URI.
- Private Claims: Custom claims created to share information between parties that agree on their meaning (e.g., an internal user ID).
Example Payload (JSON):
This example payload contains a mix of registered and private claims.
{
"sub": "1234567890",
"name": "John Doe",
"admin": true,
"exp": 1516239022
}- Registered Claims:
sub: The subject of the token (the user’s ID).exp: The expiration time of the token.
- Public Claim:
name: While not registered,nameis a common claim defined by the OIDC standard, often used for the user’s full name.
- Private Claim:
admin: A custom claim whose meaning is specific to the application (e.g., a boolean flag indicating administrative privileges).
3. Signature
The signature is used to verify the token’s authenticity. It is created by taking the encoded header, the encoded payload, a secret key (if using HMAC) or a private key (if using RSA/ECDSA), and signing them with the algorithm specified in the header.
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret
)
This signature ensures that the token has not been tampered with. The server verifies it using the same secret or the corresponding public key.
How JWT Authentication Works
sequenceDiagram participant User participant ClientApp as Client Application participant Server User->>ClientApp: 1. Enters credentials (e.g., username/password) ClientApp->>Server: 2. Sends credentials for authentication Server->>Server: 3. Verifies credentials alt Credentials are valid Server->>Server: 4. Creates and signs a JWT Server-->>ClientApp: 5. Returns the JWT ClientApp->>ClientApp: 6. Stores the JWT securely (e.g., in memory) end Note over ClientApp, Server: For subsequent requests: ClientApp->>Server: 7. Sends JWT in Authorization header<br>(Authorization: Bearer __token__) Server->>Server: 8. Verifies JWT signature and claims (e.g., expiration) alt Token is valid Server-->>ClientApp: 9. Grants access to the requested resource else Token is invalid Server-->>ClientApp: 10. Rejects request (e.g., 401 Unauthorized) end
Security Considerations
- Stateless but Irrevocable: Once a JWT is issued, it is valid until it expires. It cannot be easily revoked without implementing a more complex, stateful blocklist on the server. This is a critical trade-off for the scalability of statelessness.
- Payload is Visible: The payload is only encoded, not encrypted. Anyone can decode it and see its contents. Never store sensitive information (like passwords or personal secrets) in the payload.
- Signature is Critical: The security of a JWT relies on its signature. The server must always verify the signature. A past vulnerability involved tokens specifying
"alg": "none", which could trick libraries into skipping verification. Always use up-to-date, well-maintained libraries.
Related Concepts
- Authentication: JWT is a common technology for implementing token-based authentication.
- OAuth 2.0: JWTs are often used as bearer tokens in OAuth 2.0 flows.
- Hashing Algorithms: Used to create the JWT signature.
Resources & Links
Articles
-
JWT Authentication Guide - roadmap.sh A visual and straightforward guide that explains the purpose of JWTs, their structure, and how they fit into an authentication workflow.
-
Introduction to JSON Web Tokens - JWT.io The official introduction from JWT.io. It explains the fundamental workflow of JWTs, from user login to the server creating a signed token, and how the client sends it back for subsequent requests. It’s the canonical source for understanding the basic mechanism.
-
What Is a JWT? - Postman Blog A practical guide from the Postman blog that breaks down what a JWT is and why it’s used. It covers the three parts of a JWT (Header, Payload, Signature) and provides a clear explanation of how stateless authentication with tokens works in modern APIs.
Videos
-
JWT Explained - YouTube A clear and concise video that visually explains the structure of a JSON Web Token and its role in authentication. It walks through the process of signing and verifying a token, making the abstract concepts easy to grasp.
-
What is JWT and How does it work? - YouTube This video provides a detailed walkthrough of JWTs, covering the token structure, the difference between encoding and signing, and the complete authentication flow. It’s a great resource for understanding both the “what” and the “how” of using JWTs.