Spring Auth Server & Resource Server Example

Overview

This project demonstrates a minimal Spring Authorization Server (spring-auth-server) and a Spring Resource Server (resource-server) setup using JWT-based authentication. The setup is tailored for Postman-only client credentials flow, suitable for demos or learning purposes.

---

Spring Authorization Server

Spring Authorization Server is a framework from Spring for building your own OAuth2 / OpenID Connect compliant Authorization Server.

Key Points:

• Provides endpoints for issuing access tokens, refresh tokens, and exposing JWKS for JWT verification.
• Can be used to implement OAuth2 flows like client credentials, authorization code, password, refresh token, etc.
• Advantages over other servers like Keycloak:
  • Lightweight and fully native Spring integration.
  • No additional server setup or UI required (Keycloak requires standalone deployment).
  • Fully customizable using Spring Security configuration.
  • Great for learning and demos, or when you want a simple, embedded authorization server.

Spring is planning to integrate Spring Authorization Server fully with Spring Security 7, which will further streamline OAuth2 support directly within Spring Security.

Our Implementation: spring-auth-server

• Basic Authorization Server using only one YAML configuration file (application.yml).
• Issues access tokens based on client credentials only — e.g., Postman can request a token; no login forms or browser interactions are required.
• Minimal setup, but extendable for:
  • Multiple clients
  • Different grant types (authorization code, refresh token)
  • PKCE, consent screens, custom claims, roles, and scopes

Example YAML Configuration:

spring:
  security:
    oauth2:
      authorizationserver:
        client:
          postman-client:
            registration:
              client-id: postman-client
              client-secret: "{noop}postman-secret"
              client-authentication-methods: client_secret_basic
              authorization-grant-types: client_credentials
              scopes: read, write
            require-authorization-consent: false

• {noop} indicates a plaintext secret for demo purposes.
• Only client_credentials grant type is enabled.
• No login form or consent page is required.

---

Resource Server

A Resource Server is essentially a microservice exposing APIs that are protected by access tokens. Every microservice in a microservices architecture can include Resource Server logic to validate JWTs issued by the Authorization Server.

Our Implementation: resource-server

• Protects all Employee CRUD APIs (/api/v1/employees/**).
• Validates JWT tokens issued by spring-auth-server using the JWKS endpoint.
• Any request without a valid Bearer token is 401 Unauthorized.

Resource Server YAML:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: http://localhost:9000/oauth2/jwks

• jwk-set-uri points to the Authorization Server’s public keys.
• Only valid tokens can access protected APIs.

---

Sample API Calls

1️⃣ Generate Access Token (Client Credentials)

URL:

POST http://localhost:9000/oauth2/token

Headers:

Authorization: Basic base64(postman-client:postman-secret)
Content-Type: application/x-www-form-urlencoded

Body:

grant_type=client_credentials&scope=read

Response Example:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read"
}

---

2️⃣ Get All Employees (Protected Resource)

URL:

GET http://localhost:8080/api/v1/employees

Headers:

Authorization: Bearer <access_token>

Response Example:

[
  {
    "id": 1,
    "name": "John Doe",
    "department": "IT",
    "salary": 50000
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "department": "HR",
    "salary": 55000
  }
]

You must include a valid access token from the Authorization Server to access this API.

---

Postman Collection

We provide a Postman collection for testing:

1. Generate Access Token: Call /oauth2/token from spring-auth-server using client credentials.
2. Use Access Token: Call all Employee CRUD APIs in resource-server by setting the Authorization header as Bearer <access_token>.

Import the collection, set the access_token variable, and you can test all APIs step by step.

---

Step-by-Step Instructions to Run

Step 1: Clone the Project

git clone <repository-url>
cd <repository-folder>

Step 2: Build Both Projects

cd spring-auth-server
mvn clean install

cd ../resource-server
mvn clean install

Step 3: Run Servers

cd spring-auth-server
mvn spring-boot:run

cd ../resource-server
mvn spring-boot:run

• spring-auth-server runs on http://localhost:9000
• resource-server runs on http://localhost:8080

Step 4: Import Postman Collection

1. Open Postman → Import → Select postman_collection.json
2. Generate an access token from the Authorization Server and set it in the collection variable access_token.

Step 5: Test APIs

1. Call /oauth2/token to get a JWT token.
2. Use the token in all /api/v1/employees/** requests to test CRUD operations.

---

Current Implementation Details

• Only one grant type is supported: client_credentials.
• No login form, no authorization code flow — Postman-only demo.
• Access tokens are JWTs, validated by the Resource Server.
• YAML configuration (application.yml) is enough for the demo setup.

Extendability Examples:

• Add multiple clients with different scopes
• Enable authorization code flow for browser-based login
• Add refresh tokens, custom claims, roles, PKCE
• Integrate with database or LDAP for dynamic client/user management

---

Summary

• Spring Authorization Server: Issues JWT access tokens, lightweight and fully Spring-native.
• Resource Server: Protects APIs by validating JWT tokens; essentially a microservice with protected endpoints.
• Demo Setup: Postman-only client credentials flow with /api/v1/employees CRUD APIs.
• Step-by-step instructions provided to run and test.

---

License

Free Software, by Siraj Chaudhary