Unpacking JSON Web Tokens (JWT): Architecture, Security, and Client-Side Processing
In modern web development, particularly within distributed microservices and Single Page Applications (SPAs), traditional session-based authentication has largely been superseded by stateless protocols. At the forefront of this shift is the JSON Web Token (JWT).
JWTs (pronounced "jots") are an open industry standard (RFC 7519) that define a compact, self-contained method for securely transmitting information between parties as a JSON object. Because this information can be digitally signed, it can be verified and trusted by backend servers without requiring an active database lookup for every request.
1. The Anatomy of a JSON Web Token
When you encounter a JWT in an HTTP Authorization header or local storage, it appears as a long, seemingly random string of gibberish. However, it is highly structured. Every standard JWT is composed of exactly three parts, separated by periods (.): Header.Payload.Signature.
Part 1: The Header
The header typically consists of two parts: the type of the token (which is "JWT") and the signing algorithm being used, such as HMAC SHA256 or RSA. This JSON object is then Base64Url encoded to form the first segment of the token.
Part 2: The Payload (Claims)
The second part of the token is the payload, which contains the "claims." Claims are statements about an entity (typically, the user) and additional data. There are three types of claims:
- Registered Claims: Predefined claims that are highly recommended to provide useful, interoperable claims (e.g.,
iss(issuer),exp(expiration time),sub(subject)). - Public Claims: Custom claims defined by the implementation. To avoid collisions, they should be defined in a collision-resistant namespace.
- Private Claims: Custom claims created to share information between specific parties (e.g., passing a
user_role).
Part 3: The Signature
To create the signature part, the server takes the encoded header, the encoded payload, a secret key, and the algorithm specified in the header, and signs them. If you use the HMAC SHA256 algorithm, the signature is created in this way:
HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), secret_key)
If a malicious actor intercepts the token, changes their user_role, and recalculates the Base64 payload, the signature verification will instantly fail on the server, resulting in a rejected request.
2. Base64Url Encoding vs. Encryption (The Security Fallacy)
One of the most dangerous misconceptions in web development is assuming that a JWT is secure from prying eyes simply because it looks unreadable. Standard JWTs (JWS) are encoded, not encrypted.
Encoding is simply a mechanism to translate data into a format that can be safely transmitted over HTTP. Because it is merely encoded, anyone who possesses the token string can easily decode the header and the payload. Security Best Practice: Because the payload is visible to anyone who captures the token, you must never place highly sensitive data—such as passwords or credit card numbers—inside a JWT payload.
3. Client-Side Cryptography
When developing front-end applications, pasting your active bearer tokens or secret keys into random, third-party decoding websites introduces a severe security vulnerability. If those servers log HTTP requests, your tokens could be harvested.
The RapidCalc JWT Tool eliminates this risk entirely by adhering to a strict local-first architecture. Both the decoding logic and the cryptographic HMAC SHA-256 encoding logic run entirely within your device's RAM using JavaScript's native Web Crypto API. The data never traverses a network.