Vassago PoC

Distributed authentication with security through external credential management

Why this exists

Vassago PoC tests the feasibility of a distributed system that offloads credential management and cryptographic signing to a specialized tool (OpenBao). Instead of storing or handling secrets in application memory, this proof of concept demonstrates how a backend service can remain stateless by delegating database credential generation and JWT signing to an external vault, reducing the attack surface for a future authorization module.

Prerequisites

• Docker (v20.10+) and Docker Compose (v2.0+)
• Node.js (v18+) — only if running stress tests with k6
• curl or Postman — for testing HTTP endpoints

No additional installation of Java, Maven, or databases is required; everything runs containerized.

Installation

1. Clone the repository:

git clone <repository-url>
cd vassagoPoc

2. Create the environment file:

cp .env.example .env

3. Start all services:

docker compose up

Wait for the output to show vassago-app | Started VassagoPoCApplication.... The application will be ready when OpenBao, PostgreSQL, and the initialization script complete (typically 10–15 seconds).

Verify services are running:

docker compose ps

You should see:

• openbao-dev (port 8200)
• vassago-db (port 5432)
• vassago-app (port 8080)
• openbao-init (completed)

Usage

Register a user

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secretpass123"}'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "alice",
  "passwordHash": "$2a$10$..."
}

Login and receive JWT

curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secretpass123"}'

Response:

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJ1c2VybmFtZSI6ImFsaWNlIiwiaWF0IjoxNzEyMzQ1Njc4LCJleHAiOjE3MTIzNDkyNzh9.vault:v1:...

Verify JWT

curl -X GET http://localhost:8080/auth/verify \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."

Response:

{
  "valid": true,
  "timestamp": 1712345678
}

Run stress test

Install k6:

# macOS
brew install k6

# Linux
sudo apt-get install k6

# Windows (via Chocolatey)
choco install k6

Execute the stress test:

k6 run stress-test.js

The test stages 50 concurrent users for 1 minute, ramps to 200 for 30 seconds, then back to 0. Each iteration logs in and checks response time is under 1000 ms.

Overview

Architecture: Spring Boot WebFlux application with reactive R2DBC for PostgreSQL. At startup, OpenBaoCredentialsService retrieves ephemeral database credentials (1-hour TTL) from OpenBao's database secrets engine, eliminating static credentials in the codebase. On login, OpenBao signs JWTs using ES256 via its transit engine; the private key never leaves OpenBao. JWT verification also delegates to OpenBao's transit engine. SecurityConfig permits only /auth/register, /auth/login, and /auth/verify without authentication; all other endpoints require a valid Bearer token. The service uses BCrypt for password hashing and stores only username and hashed password in the database.