Este es un proyecto Spring Boot diseñado para implementar autenticación y autorización basada en JWT (JSON Web Tokens). El proyecto sigue principios de Domain-Driven Design (DDD) y utiliza una arquitectura limpia y modular para gestionar usuarios y roles.
El proyecto está estructurado siguiendo una arquitectura híbrida que combina Domain-Driven Design (DDD) con Arquitectura Hexagonal (Ports and Adapters). El dominio es el núcleo de la aplicación, mientras que la infraestructura se organiza siguiendo el patrón de adaptadores de entrada y salida.
jwt-app-security/
│
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/
│ │ │ └── bkseducate/
│ │ │ └── jwt_app_security/
│ │ │ ├── JwtAppSecurityApplication.java # Clase principal de Spring Boot
│ │ │ │
│ │ │ ├── domain/ # Capa de Dominio (DDD)
│ │ │ │ ├── users/ # Agregado de Usuarios
│ │ │ │ │ └── model/
│ │ │ │ │ └── aggregates/
│ │ │ │ │ └── UserModel.java # Modelo de Usuario
│ │ │ │ │
│ │ │ │ └── roles/ # Agregado de Roles
│ │ │ │ └── model/
│ │ │ │ └── aggregates/
│ │ │ │ └── Rol.java # Modelo de Rol
│ │ │ │
│ │ │ └── infrastructure/ # Capa de Infraestructura (Hexagonal)
│ │ │ ├── adapter/ # Adaptadores
│ │ │ │ └── in/ # Adaptadores de Entrada (Inbound)
│ │ │ │ └── controller/ # Controladores REST
│ │ │ │ └── HealthController.java
│ │ │ │
│ │ │ └── config/ # Configuraciones del framework
│ │ │ └── OpenApiConfig.java # Configuración de Swagger/OpenAPI
│ │ │
│ │ └── resources/
│ │ └── application.properties # Configuración de la aplicación
│ │
│ └── test/
│ └── java/
│ └── com/
│ └── bkseducate/
│ └── jwt_app_security/
│ └── JwtAppSecurityApplicationTests.java # Tests de la aplicación
│
├── docs/ # Documentación
│ ├── swagger-openapi-installation.md # Guía de Swagger/OpenAPI
│ └── database-setup.md # Guía de configuración de MySQL
│
├── pom.xml # Configuración de Maven
├── mvnw # Maven Wrapper (Unix)
├── mvnw.cmd # Maven Wrapper (Windows)
└── README.md # Este archivo
El proyecto sigue el patrón de Arquitectura Hexagonal (también conocida como Ports and Adapters), que separa la lógica de negocio (dominio) de los detalles técnicos (infraestructura):
- Domain: Contiene la lógica de negocio pura, independiente de frameworks
- Infrastructure: Contiene adaptadores que conectan el dominio con el mundo exterior
- adapter/in: Adaptadores de entrada (controladores REST, eventos, etc.)
- adapter/out: Adaptadores de salida (repositorios, servicios externos, etc.)
El proyecto utiliza las siguientes tecnologías y dependencias:
- spring-boot-starter-webmvc: Framework web para crear APIs REST
- spring-boot-starter-data-jpa: Persistencia de datos con JPA/Hibernate
- spring-boot-devtools: Herramientas de desarrollo (recarga automática)
- mysql-connector-j: Conector para MySQL
- lombok: Reduce código boilerplate (getters, setters, constructores)
- springdoc-openapi-starter-webmvc-ui: Documentación automática de API con Swagger/OpenAPI
- spring-boot-starter-webmvc-test: Testing de controladores web
- spring-boot-starter-data-jpa-test: Testing de repositorios JPA
En Domain-Driven Design, un agregado es un cluster de objetos de dominio que se trata como una unidad única. Los agregados tienen una raíz de agregado que es la única entrada al agregado.
Ubicación: com.bkseducate.jwt_app_security.domain.users.model.aggregates
Clase: UserModel.java
Representa un usuario del sistema con la siguiente estructura:
- id: Long // Identificador único del usuario
- username: String // Nombre de usuario (único)
- password: String // Contraseña (debe estar encriptada)
- email: String // Correo electrónico del usuarioPropósito:
- Gestionar la información de autenticación de los usuarios
- Servir como entidad principal para el sistema de autenticación JWT
Ubicación: com.bkseducate.jwt_app_security.domain.roles.model.aggregates
Clase: Rol.java
Representa un rol o permiso en el sistema:
- id: Long // Identificador único del rol
- name: String // Nombre del rol (ej: ADMIN, USER, MODERATOR)Propósito:
- Definir los diferentes niveles de acceso y permisos
- Establecer la autorización basada en roles (RBAC - Role-Based Access Control)
El proyecto utiliza perfiles de Spring Boot para separar la configuración entre entornos:
application.properties: Configuración base y común a todos los entornosapplication-dev.properties: Configuración específica para desarrollo (activo por defecto)application-prod.properties: Configuración específica para producción
# Base de datos MySQL - Desarrollo
spring.datasource.url=jdbc:mysql://localhost:3306/jwt_security_db?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC&createDatabaseIfNotExist=true
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
# JPA/Hibernate - Desarrollo
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=truePara configurar tu entorno de desarrollo:
- Copia
application-dev.properties.examplecomoapplication-dev.properties - Actualiza las credenciales de base de datos con tus valores locales
# Base de datos MySQL - Producción (usar variables de entorno)
spring.datasource.url=${DB_URL}
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
# JPA/Hibernate - Producción
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=falsePara producción, configurar variables de entorno:
export DB_URL=jdbc:mysql://servidor:3306/jwt_security_db?useSSL=true&requireSSL=true
export DB_USERNAME=usuario_produccion
export DB_PASSWORD=contraseña_segura
export SPRING_PROFILES_ACTIVE=prodDesarrollo (por defecto):
./mvnw spring-boot:run
# O explícitamente:
./mvnw spring-boot:run -Dspring.profiles.active=devProducción:
./mvnw spring-boot:run -Dspring.profiles.active=prod
# O mediante variable de entorno:
export SPRING_PROFILES_ACTIVE=prod
./mvnw spring-boot:run- Java 17 o superior
- Maven 3.6+ (incluido con Maven Wrapper)
- MySQL 8.0+ (o cualquier base de datos compatible)
-
Clonar o descargar el proyecto
-
Configurar la base de datos:
- Instalar y ejecutar MySQL 8.0+ en tu máquina local
- Crear una base de datos MySQL llamada
jwt_security_db:CREATE DATABASE jwt_security_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
- Copiar
application-dev.properties.examplecomoapplication-dev.properties - Actualizar
application-dev.propertiescon tus credenciales de MySQL:spring.datasource.username=tu_usuario spring.datasource.password=tu_contraseña
-
Compilar el proyecto:
# Windows ./mvnw.cmd clean install # Linux/Mac ./mvnw clean install
-
Ejecutar la aplicación:
# Windows ./mvnw.cmd spring-boot:run # Linux/Mac ./mvnw spring-boot:run
O ejecutar directamente la clase
JwtAppSecurityApplicationdesde tu IDE. -
Verificar que está funcionando:
- La aplicación debería iniciar en
http://localhost:8080(o el puerto configurado) - Revisar los logs para confirmar que no hay errores
- Acceder a Swagger UI en:
http://localhost:8080/swagger-ui.html - Ver la especificación OpenAPI en:
http://localhost:8080/v3/api-docs
- La aplicación debería iniciar en
- Estructura base de Spring Boot
- Configuración de Maven
- Modelos de dominio (UserModel y Rol)
- Estructura DDD básica con Arquitectura Hexagonal
- Configuración de MySQL con perfiles (dev/prod)
- Pool de conexiones HikariCP configurado
- Configuración JPA/Hibernate optimizada por entorno
- Swagger/OpenAPI para documentación de API
- Controlador de ejemplo (HealthController) con documentación Swagger
- Repositorios JPA: Interfaces para acceso a datos
- Servicios: Lógica de negocio para usuarios y roles
- Controladores REST: Endpoints para autenticación y gestión
- Configuración de Seguridad: Spring Security con JWT
- Filtros JWT: Validación de tokens en cada request
- DTOs: Objetos de transferencia de datos
- Mappers: Conversión entre entidades y DTOs
- Validaciones: Validación de datos de entrada
- Manejo de Excepciones: Controladores de excepciones globales
¿Qué es DDD? DDD es un enfoque de desarrollo de software que se centra en el dominio del negocio. En lugar de pensar primero en la base de datos o la interfaz, DDD comienza con el dominio (las reglas de negocio).
Ventajas:
- Código más expresivo y cercano al lenguaje del negocio
- Mejor separación de responsabilidades
- Facilita el mantenimiento y la evolución
- Independencia de frameworks y tecnologías
Estructura en este proyecto:
domain/
└── [entidad]/
└── model/
└── aggregates/
└── [Entidad].java
¿Qué es la Arquitectura Hexagonal? La Arquitectura Hexagonal, también conocida como Ports and Adapters, es un patrón arquitectónico que separa la lógica de negocio (dominio) de los detalles técnicos (infraestructura). El dominio está en el centro, rodeado por adaptadores que se conectan con el mundo exterior.
Ventajas:
- Independencia del dominio: El dominio no depende de frameworks ni tecnologías específicas
- Testabilidad: Fácil de testear sin necesidad de bases de datos o servicios externos
- Flexibilidad: Cambiar de framework o tecnología sin afectar el dominio
- Separación clara: Límites bien definidos entre capas
Estructura en este proyecto:
infrastructure/
├── adapter/
│ ├── in/ # Adaptadores de entrada (inbound)
│ │ └── controller/ # Controladores REST
│ └── out/ # Adaptadores de salida (outbound)
│ └── persistence/ # Repositorios JPA (futuro)
└── config/ # Configuraciones del framework
└── OpenApiConfig.java # Configuración de Swagger/OpenAPI
Conceptos clave:
- Ports: Interfaces que definen cómo el dominio se comunica con el exterior
- Adapters: Implementaciones concretas que conectan el dominio con tecnologías específicas
- Inbound Adapters: Reciben requests del exterior (controladores REST, eventos)
- Outbound Adapters: Envían datos al exterior (bases de datos, servicios externos)
¿Qué es JWT? JWT es un estándar abierto (RFC 7519) para transmitir información de forma segura entre partes como un objeto JSON. Es especialmente útil para autenticación y autorización en aplicaciones web.
Estructura de un JWT:
header.payload.signature
Flujo típico:
- Usuario se autentica con credenciales
- Servidor valida credenciales y genera un JWT
- Cliente almacena el JWT (localStorage, cookies, etc.)
- Cliente envía el JWT en cada request (header Authorization)
- Servidor valida el JWT y permite o deniega el acceso
¿Qué es Spring Boot? Spring Boot es un framework que simplifica el desarrollo de aplicaciones Spring. Proporciona configuración automática, servidor embebido y convenciones sobre configuración.
Características principales:
- Auto-configuración inteligente
- Servidor embebido (Tomcat, Jetty, Undertow)
- Producción lista (actuators, métricas)
- Sin necesidad de configuración XML
-
Implementar Spring Security:
- Configurar la seguridad básica
- Crear filtros de autenticación
-
Implementar JWT:
- Generar tokens JWT
- Validar tokens en cada request
- Manejar refresh tokens
-
Crear Repositorios:
UserRepositoryextendiendoJpaRepositoryRolRepositoryextendiendoJpaRepository
-
Crear Servicios:
UserServicecon lógica de negocioAuthServicepara autenticaciónJwtServicepara manejo de tokens
-
Crear Controladores:
AuthControllerpara login/registroUserControllerpara gestión de usuarios
-
Agregar Validaciones:
- Usar Bean Validation (@Valid, @NotNull, etc.)
- Validar emails, contraseñas seguras, etc.
-
Manejo de Errores:
- Crear excepciones personalizadas
- Implementar
@ControllerAdvicepara manejo global
-
Documentación API:
- Integrar Swagger/OpenAPI
- Documentar todos los endpoints
- Guía de Configuración de Base de Datos - Configuración detallada de MySQL
- Guía de Swagger/OpenAPI - Documentación de API
- Spring Boot Documentation
- Spring Security Documentation
- JWT.io - Herramienta para debuggear JWT
- Domain-Driven Design
- Maven Documentation
- MySQL Documentation
Este proyecto está en desarrollo activo. Las contribuciones son bienvenidas.
Este proyecto es un proyecto de demostración para fines educativos.
Nota: Este proyecto está diseñado como base para implementar autenticación JWT. La estructura DDD proporciona una base sólida para escalar y mantener el código a medida que el proyecto crece.