Designing Token‑Based Authentication: OAuth2, JWT, and System Architecture

Background

As enterprise applications proliferate, managing user data separately creates information silos; a unified account management system is essential for platformization, enabling single sign‑on, third‑party login, and consistent authorization across services.

Key Terminology

Third‑party application (client)

HTTP service (service provider)

Resource Owner (user)

User Agent (browser)

Authorization server

Resource server

Why Token‑Based Authentication?

Stateless: the token carries all user information, eliminating server‑side session storage.

Performance: token validation avoids database or remote service lookups.

Cross‑domain support: tokens work across browsers and mobile apps, unlike cookies.

Typical Token Flow

User submits login credentials (or calls a token endpoint) to the authentication service.

The service validates the credentials and returns an access token (and optionally a refresh token).

The client includes the token in HTTP request headers when calling APIs.

Each microservice validates the token and processes the request.

The service returns the requested resource or data.

Functional Goals

Provide a standardized security authentication process that allows heterogeneous systems or cross‑service interactions to integrate and authenticate uniformly, supporting token issuance, validation, and renewal.

Technical Choices

System authorization adopts the OAuth2 password‑grant flow. Tokens follow the JWT (JSON Web Token) standard (RFC 7519), which is compact, self‑contained, and suitable for SSO scenarios.

OAuth2 Grant Types Overview

Authorization code – used between client and server applications.

Implicit – for mobile or web apps where the token is issued directly in the browser.

Password – trusted clients obtain a token using the resource owner's username and password.

Client credentials – service‑to‑service authentication where the client acts on its own behalf.

JWT Details

JWT is a JSON‑based open standard for transmitting claims securely; it can be signed or encrypted, is compact, and is ideal for distributed single sign‑on (SSO) scenarios.

Authentication Process Logic

System Authorization

Third‑party client uses its client ID/secret and the resource owner's credentials to obtain an access token from the authorization server.

System Authentication

The client presents the access token to the resource server; the server validates the token, the client identity, and the user identity, then grants access based on the user's permissions.

Token Renewal

When the access token expires, the client uses a refresh token to request a new access token, extending the session without re‑entering credentials.

API Design Highlights

Authorization Credential Endpoint

Issues an access token after validating client identity and resource owner credentials.

Credential Renewal Endpoint

Validates the refresh token and issues a new access token.