Access Token

Overview

The Access Token pattern addresses the need for microservices systems to identify the user making requests, since those requests pass from microservice to microservice, starting at the API Gateway. Alongside this need, it must also guarantee the security quality attribute through authentication and authorisation mechanisms.

Problem

In a microservices architecture, requests arrive at the API Gateway and are forwarded to backend microservices. Each microservice may need to know who the caller is, what role they have, and whether they are permitted to perform the operation. If each microservice implements its own security logic, several problems arise:

• Unauthenticated requests can enter the internal network
• Development teams must implement security logic correctly in every microservice — any vulnerability in one creates a system-wide risk
• Different types of users (login users, API users) require different authentication implementations across all services

Authentication

Authentication consists of verifying the identity of a user or API client. The preferred approach is to implement authentication in the API Gateway, since it resolves all the problems listed above.

Centralising this security logic in the API Gateway ensures there is only one place where authentication must succeed, reduces the probability of security vulnerabilities, and delegates to the API Gateway the responsibility of authenticating different types of users — abstracting that complexity from the backend microservices.

For a login user, the process begins with an HTTP POST /login request with credentials (id and password). The API Gateway authenticates the user and, on success, returns a token for the user to include in subsequent requests. After receiving a request with the token, the API Gateway verifies the user's identity and forwards the request along with the token to the responsible microservices, so they can identify and authenticate the user.

For an API user, the process begins directly with the desired request, sending the credentials in the request header. The API Gateway authenticates the user based on the credentials provided and, on success, generates a token that is passed to the microservices.

Authorisation

Authorisation consists of verifying whether a user has permission to perform the requested operation on specific data. The two mechanisms are:

• Role-based — each user is marked with one or more roles that grant permissions for certain operations
• ACLs (Access Control Lists) — specific users or roles are defined with permissions to perform an operation on a business object or aggregate

Implementing authorisation in the API Gateway has the same advantages as centralised authentication, but with one limitation: only role-based can easily be used, because ACLs require knowledge of the microservices' business objects — which the Gateway does not have.

Implementing authorisation in each microservice allows both role-based and ACLs. ACLs are more straightforward here because the microservice has full knowledge of its own business objects. The OAuth 2.0 protocol can be used for implementing both authentication and authorisation, for both API users and login users.

Token Types

Two types of tokens exist: opaque tokens and transparent tokens.

An opaque token normally uses UUIDs for user identification. However, these are not recommended for microservices architectures, because they reduce performance and increase latency — validating an opaque token requires a synchronous request to a security service to validate and retrieve the user's data.

A transparent token does not require requests to third-party services for validation and data retrieval, resolving the problems of opaque tokens. JWT (JSON Web Token) is the recommended pattern for implementing this approach. See the JWT pattern page for details.

Trade-offs

When to Use