Build a Spring Boot 3.x Microservice OAuth2 Authorization Server from Scratch

Technical Stack

JDK 21, Gradle 8.10.1, Spring Boot 3.3.3, Spring Cloud 2023.0.3, Spring Cloud Gateway 4.1.5, Spring Security 6.3.3 with OAuth2 Authorization Server 1.3.2, H2 database, MyBatis 3.0.3, Flyway, and standard Spring MVC components.

Core Features

api-gateway acts as the gateway, auth-service as the unified authentication server, and order-service as a business service.

api-gateway proxies requests to auth-service and order-service and integrates oauth2-resource-server to validate JWT tokens.

auth-service uses H2 (switchable to MySQL) with MyBatis and Flyway; migration scripts are placed in db/migration.

H2 stores data in a local file, preserving state across restarts.

JWT RSA key pair is pre‑generated so tokens remain valid after service restarts.

All OAuth2 data (clients, tokens, etc.) is persisted in the database via the default JDBC repository.

order-service does not embed OAuth2 components; it relies on the gateway to forward authenticated requests via the Authorization header.

Project Structure

tree -I '.gradle|.idea|gradle|buildSrc|build'
.
├── api-gateway
│   └── src/main/java/top/flyeric/gateway/...
├── auth-service
│   └── src/main/java/top/flyeric/auth/...
├── order-service
│   └── src/main/java/top/flyeric/order/...
├── build.gradle
├── gradlew
└── settings.gradle

Operation Steps

01 Start Services

Run each module. Default ports are:

- api-gateway: 8080
- auth-service: 8081
- order-service: 8082

02 View Authorization Server Metadata

Open the following URL to see the OpenID Connect discovery document (JSON metadata):

http://localhost:8081/.well-known/openid-configuration

The document contains endpoints such as authorization_endpoint, token_endpoint, jwks_uri, etc.

03 Obtain Authorization Code

Navigate to the authorization endpoint (through the gateway) to start the standard OAuth2 authorization‑code flow:

http://localhost:8080/api/auth-service/oauth2/authorize?response_type=code&client_id=eric-client&scope=openid&redirect_uri=http://127.0.0.1:8080/public/home

The login page (username/password) authenticates the user and redirects back with a code query parameter.

04 Exchange Code for Access Token

Send a POST request to /oauth2/token using client_secret_basic authentication. The Authorization header must contain the Base64‑encoded client_id:client_secret value.

# Generate Base64 credentials
echo -n "eric-client:secret" | base64
# Result: ZXJpYy1jbGllbnQ6c2VjcmV0

Request body (application/x-www-form-urlencoded):

grant_type=authorization_code&code=YOUR_CODE&redirect_uri=http://127.0.0.1:8080/public/home

The response includes access_token, refresh_token, token type, expires_in, etc.

05 Call Protected APIs

Use the obtained access_token in the Authorization: Bearer <token> header.

Auth‑service OIDC user‑info endpoint: http://localhost:8081/userinfo Order‑service order details endpoint: http://localhost:8082/api/orders/{id} (accessed through the gateway at /api/order-service/**)

Source Repository

GitHub repository: https://github.com/flyeric0212/eric-microservices-oauth2-demo

Reference Documentation

Spring Authorization Server Getting Started: https://docs.spring.io/spring-authorization-server/reference/getting-started.html