Overview

JWT (JSON Web Token) is the recommended pattern for implementing transparent tokens in microservices architectures. It represents the identity and roles of a user securely between two entities, without requiring a synchronous call to a security service to validate the token.

Problem

As described in the Access Token pattern, two types of tokens exist: opaque and transparent. An opaque token (typically using UUIDs) is not recommended for microservices architectures because validating it requires a synchronous request to a security service to retrieve the user's data — reducing performance and increasing latency for every request that passes through multiple microservices.

Solution

A transparent token resolves this problem: validating and obtaining data from a transparent token does not require requests to third-party services. JWT is the recommended pattern for this approach. A JWT represents the user's identity and roles securely between two entities.

Token Structure

A JWT token contains a JSON object in its payload that includes data such as:

  • The identity of the user (user ID)
  • The role of the user (for authorisation decisions)
  • Additional information about the token, such as the expiration date

To guarantee the security of the information the token represents, cryptography is used: tokens are signed with a key known only to the creator and receiver of the token. Any microservice that receives the token can verify its integrity using that shared key, without contacting an external security service.

OAuth 2.0

The OAuth 2.0 authorisation protocol is relevant to the implementation of Access Tokens and JWT. Although its primary objective is to allow third-party applications to access HTTP services, it can be used for implementing authentication and authorisation in microservices architectures — for both API users and login users. Using OAuth 2.0 is advantageous because it implements the necessary security infrastructure reliably, removing that responsibility from developers. The Spring OAuth2 framework is one example of its implementation in a microservices context.

Trade-offs

Benefits

  • No synchronous calls to a security service required for token validation — lower latency
  • Self-contained — the token carries the user's identity and roles directly
  • Standardised format (RFC 7519) with broad library support across languages and frameworks
  • Cryptographic signature ensures token integrity

Drawbacks

  • Token revocation is difficult — a JWT remains valid until it expires, even if the user's permissions change
  • The token payload is Base64-encoded, not encrypted by default — do not include sensitive data without additional encryption
  • Token size is larger than an opaque UUID, increasing request overhead slightly

When to Use

Apply JWT when:

  • You need a transparent token that microservices can validate locally without a round-trip to a security service
  • User identity and role information must be carried across multiple microservices within a request
  • Performance and low latency are priorities

Consider alternatives when:

  • Immediate token revocation is required — opaque tokens with a central validation service allow instant revocation at the cost of latency

References