Designing Secure Microservice Authentication with Spring Boot 3 and OAuth2

Introduction

Spring Boot 3 GA was released on 2022‑11‑24. Key changes include:

Spring Framework upgraded to 6.x

Minimum JDK version 17+

Jakarta Servlet replaces Javax Servlet

SpringFox Swagger replaced by SpringDoc

Support for /META-INF/spring.factories removed

Faster startup and lower memory usage

Many configuration property names and usage patterns changed

Spring Security OAuth2 changes:

The legacy spring-security-oauth2 project is no longer maintained

Official SDK provides three starter modules:

spring-boot-starter-oauth2-client

spring-boot-starter-oauth2-resource-server

spring-boot-starter-oauth2-authorization-server

Microservice Authentication Scenarios

Typical front‑end clients: PC web, mobile H5, mini‑programs, native apps.

Backend microservices are usually organized into three layers:

API Gateway – unified authentication entry point, validates tokens and returns 401 on failure.

Auth Service – dedicated authorization server handling login, registration, and OAuth2 token issuance.

Business Services – contain core business logic and trust requests already authenticated by the gateway.

OAuth2 components:

Authorization Server

Resource Server

Client

External systems may act as OAuth2 clients using client‑credentials flow.

- API Gateway: validates JWT token on every request; rejects invalid tokens with 401.
- Auth Service: issues and manages OAuth2 tokens, stores user permissions (e.g., RBAC).
- Business Services: rely on the gateway‑provided user identity, no direct OAuth2 integration.
- Front‑end Apps: include access token in request headers; use refresh token to obtain new access token when expired.

Microservice Authentication Design

Overall architecture diagram:

Authentication and authorization flow diagram:

Key design points:

Integrate spring-boot-starter-oauth2-authorization-server into Auth Service to build a unified authorization server; replace the default login page with a custom UI if needed.

Auth Service generates JWT tokens with a pre‑generated RSA key pair; the public key is shared with the gateway so token validation works even if Auth Service is down.

Persist tokens, client details, and consent data in a relational database using Spring Security’s JDBC repositories instead of the default in‑memory beans.

Implement a custom UserDetailsService in Auth Service for username/password authentication.

Expose Auth Service endpoints with permitAll() and delegate all access control to the API Gateway.

Configure the API Gateway with spring-boot-starter-oauth2-resource-server to act as a resource server; use the public key from Auth Service to build a JWT decoder.

Configure the API Gateway with spring-boot-starter-oauth2-client to act as an OAuth2 client for external providers (e.g., GitHub, Google).

Implement a custom CustomAuthorizationManager in the gateway to evaluate the user’s permission list (API whitelist) for each request.

Front‑end applications use the authorization‑code flow to obtain an access token and a refresh token, storing them in LocalStorage; refresh tokens are used to obtain new access tokens when needed.

Front‑end applications fetch the current user’s functional permissions from Auth Service to render menus, pages, and buttons dynamically.

Third‑party systems act as OAuth2 clients using client‑credentials flow (client ID and secret) to obtain access tokens without user interaction.

Backend business services trust the user identity propagated via request headers from the gateway, eliminating repeated authentication checks.

Benefits

Centralized authentication and authorization : all security logic resides in the API Gateway and Auth Service, simplifying backend services.

Improved security : the gateway serves as the first line of defense, shielding internal services.

Scalability : new services can be added without duplicating authentication code.

Maintainability : security policies are managed in a single place, easing updates and audits.

Further Reading

Permission Model Design – https://mp.weixin.qq.com/s?__biz=Mzk0NDI1NzI2Mw==&mid=2247485432&idx=1&sn=9e3b1da4c08bf87e575b46e2909fb179&chksm=c3262678f451af6ee184061d28fe3cdc6998582abf7fd37701ba0a4ae8e9f7ccd03e5baad922&scene=21

Appendix

OAuth2 component diagram:

Authorization server details:

Authorization code acquisition and exchange flow (illustrated in the original images).

Token request example (authorization code → access token):

OAuth2 authorization record table (schema shown in the original image).

Gateway behavior:

Requests without a token receive HTTP 401.

Requests with a valid token are routed to the target service.