ZGO Security - Hexagonal Spring Security Implementation

Modern implementation of Spring Security based on Clean/Hexagonal Architecture, using JWT with RSA-256 asymmetric encryption.

🚀 Technical Stack

• Framework: Spring Boot 3.5.13 (Spring 6.3)
• Java: 21
• Security: Spring Security 6.x (OAuth2 Resource Server, JWT RS256)
• Database: PostgreSQL 15+
• Mapping: MapStruct 1.6.3
• Utils: Lombok
• Architecture: Hexagonal (Ports & Adapters) — 100% desacoplada

🏆 Características de Calidad Empresarial

• TokenGeneratorPort: Dominio sin dependencias de infraestructura
• UserResponse DTO: El password jamás se expone al cliente
• Excepciones de dominio con HTTP semántico (409 Conflict, 403 Forbidden, 401 Unauthorized)
• UserEntity con patrón @Builder — inmutable post-construcción
• AppSecurityProperties record tipado para toda la configuración de seguridad
• @Transactional en operaciones de escritura para garantía de atomicidad

📁 Project Structure

src/main/java/org/zgo/security/
├── domain/                  # CORE BUSINESS LOGIC (Framework-independent)
│   ├── model/               # Domain Records (User, Role)
│   └── ports/               # Port Interfaces
├── application/             # APPLICATION SERVICES
│   └── service/             # Use Case Implementations
└── infrastructure/          # TECHNICAL DETAILS (Adapters & Config)
    ├── adapter/             # Infrastructure Implementations
    └── config/              # Security and Spring Bean configuration

🛠️ How to run

1. Start Database:

   docker-compose up -d

2. Set JAVA_HOME (solo para JDK 21): Asegúrate de apuntar la variable de entorno a tu instalación de Java 21 antes de ejecutar:

   $env:JAVA_HOME="C:\Java\jdk-21"

3. Compile and Run using Maven Wrapper: Se ha generado un Maven Wrapper (mvnw) para asegurar que el proyecto se corra siempre con la misma configuración de Maven en cualquier entorno.

   En Windows (PowerShell/CMD):

   .\mvnw.cmd clean spring-boot:run

   En Linux/Mac:

   ./mvnw clean spring-boot:run

🔐 Security Details

• JWT Signing: Uses RS256 (RSA with SHA-256).
• Public/Private Keys: Stored in src/main/resources/certs/.
• User Passwords: Encrypted with BCrypt.
• Exception Handling: Global @RestControllerAdvice mapping domain/security errors to HTTP 4x/5x.

🧪 Testing with Postman

Import the collection located in: postman/SpringSecurity_Collection.json

• Register: POST /api/v1/auth/register
• Login: POST /api/v1/auth/login (Returns Bearer token)
• Protected Resources: Add Authorization: Bearer <token> header.