A Full Guide to JWTs

In a modern microservices system, services need a reliable way to establish trust without querying a central database for every single incoming request. This need is precisely why JSON Web Tokens (JWTs) have become the industry standard for transmitting verifiable information between clients and servers—or directly between services.

However, while thousands of developers use JWTs daily, very few actually understand the underlying specification. This knowledge gap leaves many applications vulnerable to simple security flaws. To build bulletproof authorization systems, we must look under the hood and explore the entire JOSE (JSON Object Signing and Encryption) framework.

To appreciate the design of JWTs, it helps to understand why traditional session-based authentication breaks down at scale:

Because the token itself carries verifiable proof, any downstream service can independently validate the signature and trust the claims without querying a database. The JOSE working group began standardizing this JSON-based security approach in 2011 to provide uniform authentication across languages and systems.

In production systems, JWTs typically serve two primary roles, along with a distinct workflow for token lifecycle management:

Instead of maintaining server-side state, user roles and permissions (e.g., "role": "admin") are embedded directly into the token payload. The server evaluates these claims instantly on each request.

Federated authentication (such as "Log in with Google") relies on OpenID Connect (OIDC), an identity layer built on top of OAuth2. In this architecture:

Most authentication systems utilize two distinct token types:

A standard compact JWT appears as a single string composed of three distinct parts separated by dots (.). While it looks like random gibberish, it is simply Base64-URL encoded JSON data.

The header is a JSON object defining how the token should be parsed.

The payload contains the actual Claims (assertions about the user or token). The specification defines standard Registered Claims using compact three-letter keys:

Developers can also include Public Claims intended for common standard use, or Private Claims specific to custom application logic.

The signature protects the integrity of the token. It is created by taking the Base64-URL encoded header and payload, joining them with a dot, and passing them through the specified alg mathematical function alongside a secret or private key.

If an attacker modifies even a single character in the payload, signature recalculation will fail, causing the server to reject the token immediately.

If a JWT is a container for data, JSON Web Signature (JWS) is the specific specification that defines how to lock that container mathematically.

JWS ensures two critical properties:

Crucially, JWS does not encrypt or hide data—anyone who intercepts the token can decode Base64-URL and read the raw claims.

To assist servers in locating the correct verification key, JWS headers can include key references such as kid (Key ID), jwk (JSON Web Key), or jku (JWK Set URL).

A widespread security vulnerability occurs when code relies on the token's header to determine which algorithm to execute during verification. Attackers can exploit this by changing the header alg to "none" or switching an asymmetric algorithm like RS256 to symmetric HS256 using a public key as the secret.

Always explicitly configure your application library to accept only expected algorithms (e.g., forcing RS256) regardless of what the token header claims.

While JWS provides integrity, JSON Web Encryption (JWE) provides confidentiality. If a payload contains sensitive data that must remain hidden from unauthorized viewers, JWE transforms the payload into an opaque string that cannot be read without the private key.

The key usage direction in JWE is reversed compared to JWS:

To achieve both sender authenticity and data secrecy, developers use Nested JWTs—signing the payload with JWS first, then wrapping that signed token inside a JWE envelope. This also prevents signature removal attacks.

Because encryption requires additional parameters, a JWE compact token consists of five dot-separated parts:

JWE supports both Compact Serialization (the standard 5-part string) and JSON Serialization, which allows a single payload to be encrypted for multiple distinct recipients simultaneously.

For asymmetric cryptography to work seamlessly across heterogeneous microservice fleets, systems need a standardized way to represent and publish cryptographic keys. JSON Web Keys (JWK) standardizes key formats into clean JSON structures.

A standard JWK includes fields such as:

Depending on the algorithm, the JSON object exposes exact parameters—such as n (modulus) and e (exponent) for RSA, or x and y coordinates for Elliptic Curve keys.

To handle key rotation cleanly without downtime, Identity Providers (like Auth0 or Google) host a JSON Web Key Set (JWKS) endpoint. A JWKS is simply a JSON object holding an array of all active public keys. Downstream microservices fetch this public URL (referenced in the jku header claim) to dynamically update their verification keys whenever key rotation occurs.

At the foundation of the JOSE framework is JSON Web Algorithms (JWA), which dictates the mathematical implementations underlying all encoding, hashing, signing, and encryption tasks.

By leveraging the complete JOSE specification—structuring claims properly with JWT, securing integrity with JWS, protecting confidential data with JWE, and managing keys via JWKS—you can build resilient, stateless authorization layers across any microservice architecture.

Thanks for Reading ❤
Stay tuned for the next parts 💡

Arian