Joko Security provee autenticación y autorización mediante Tokens JWT. Puede utilizarse como microservicio independiente o embebido como librería en otra aplicación Spring Boot.
- ✅ JWT Tokens: Access y Refresh tokens con firma segura
- ✅ Spring Boot 3.3.1: Última versión estable con Spring Security 6.x
- ✅ JJWT 0.12.6: Biblioteca JWT moderna con protecciones OWASP
- ✅ Arquitectura Modular: Módulos independientes y reutilizables
- ✅ Stateless: Validación en memoria para escalabilidad
- ✅ Revocación de tokens: Almacenamiento en PostgreSQL/Redis
- ✅ Security Profiles: Diferentes tiempos de vida para tokens
- ✅ Two-Factor Auth: Soporte para TOTP/OTP
- ✅ Session Auditing: Registro de sesiones de usuario
joko-security-parent (2.0.0)
├── joko-security-core # JWT services, filtros (REQUERIDO)
├── joko-security-storage-postgres # Storage PostgreSQL para tokens
├── joko-security-web # Controllers REST (opcional)
├── joko-security-autoconfigure # Spring Boot auto-configuration
└── joko-security-starter # BOM - Todo en una dependencia
Agregar a pom.xml:
<repositories>
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/sodep/joko-security-interfisa</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>io.github.jokoframework</groupId>
<artifactId>joko-security-starter</artifactId>
<version>2.0.0</version>
</dependency>
</dependencies>Agregar a build.gradle:
repositories {
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/sodep/joko-security-interfisa")
credentials {
username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
password = project.findProperty("gpr.token") ?: System.getenv("GITHUB_TOKEN")
}
}
}
dependencies {
implementation 'io.github.jokoframework:joko-security-starter:2.0.0'
}O con Kotlin DSL (build.gradle.kts):
repositories {
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/sodep/joko-security-interfisa")
credentials {
username = project.findProperty("gpr.user") as String? ?: System.getenv("GITHUB_USERNAME")
password = project.findProperty("gpr.token") as String? ?: System.getenv("GITHUB_TOKEN")
}
}
}
dependencies {
implementation("io.github.jokoframework:joko-security-starter:2.0.0")
}Nota: Para acceder a GitHub Packages, configura tus credenciales en ~/.gradle/gradle.properties o variables de entorno. Ver docs/INTEGRATION_GUIDE.md para detalles.
joko:
security:
jwt:
secret: ${JWT_SECRET} # Mínimo 256 bits
issuer: my-app
audience: my-app-users
storage:
type: postgres # postgres | redis | in-memory
web:
enabled: false # Deshabilitar controllers de joko (usar los propios)Nota: Los TTL (Time To Live) de los tokens NO se configuran en
application.yml. Se configuran en la base de datos a través de la tablasecurity_profile.
Ver docs/INTEGRATION_GUIDE.md para guía completa de integración.
- Java 17
- Maven 3.8+
- PostgreSQL 9.4+ (o H2 para testing)
git clone https://github.com/jokoframework/security.git
cd security
git checkout feature/modular-refactor
# Opción 1: Usar script de ayuda (recomendado)
./publish.sh local
# Opción 2: Usar Maven Wrapper directamente
./mvnw clean install
# Opción 3: Usar Maven instalado globalmente
mvn clean installRecomendación: Usar ./mvnw (Maven Wrapper) para garantizar consistencia de versiones.
- Crear directorio de configuración:
mkdir -p /opt/joko-security/dev
cp src/main/resources/application.properties.example /opt/joko-security/dev/application.properties-
Editar application.properties con tus credenciales de BD
-
Configurar variables de entorno:
export ENV_VARS="/opt/joko-security/development.vars"- Inicializar base de datos:
# Crear schema y tablas
./scripts/updater fresh
# Cargar datos iniciales
./scripts/updater seed src/main/resources/db/sql/seed-data.sql- Ejecutar aplicación:
# Con Maven Wrapper (recomendado)
./mvnw spring-boot:run
# O con Maven global
mvn spring-boot:runLa aplicación estará disponible en http://localhost:8080/security
# Configurar ~/.m2/settings.xml con tu GitHub token
cp settings.xml.example ~/.m2/settings.xml
# Editar y agregar tu token
# Opción 1: Usar script de ayuda (recomendado)
./publish.sh github
# Opción 2: Usar Maven Wrapper
./mvnw clean deploy
# Opción 3: Usar Maven global
mvn clean deploy# Configurar credenciales
export ARTIFACTORY_USER="tu-usuario-sodep"
export ARTIFACTORY_PASSWORD="tu-password"
# Publicar snapshot (desarrollo)
./publish-artifactory.sh snapshot
# Publicar release (producción)
./publish.sh version 2.0.0
./publish-artifactory.sh releaseVer docs/PACKAGING_GUIDE.md y docs/ARTIFACTORY.md para instrucciones detalladas.
Refresh Token:
- Tiempo de vida largo (días/semanas)
- Permisos limitados
- Solo para obtener access tokens
- Almacenado de forma segura (cookies HTTP-only, keystore móvil)
Access Token:
- Tiempo de vida corto (minutos)
- Permisos completos
- Se renueva antes de expirar
- Almacenado en memoria (no en localStorage)
Configuran tiempos de vida de tokens según el canal:
- Web: Refresh token de horas
- Mobile: Refresh token de semanas
- Admin: Tokens más restrictivos
1. Login → Refresh Token (24h, permisos limitados)
2. Refresh → Access Token (15min, permisos completos)
3. API Calls → Authorization: Bearer {access_token}
4. Renovar antes de expirar → Repetir paso 2
Dos interfaces principales para implementar:
Valida credenciales y retorna usuarios autenticados:
@Service
public class CustomAuthManager implements JokoAuthenticationManager {
@Override
public JwtUserDetails authenticate(String username, String password) {
// Validar contra tu BD o servicio externo
User user = userRepository.findByUsername(username);
if (user != null && passwordMatches(password, user.getPassword())) {
return new JwtUserDetails(user.getId(), user.getUsername(), user.getRoles());
}
throw new BadCredentialsException("Invalid credentials");
}
}Configura reglas de seguridad y permisos por URL:
@Service
public class CustomAuthzManager implements JokoAuthorizationManager {
@Override
public void configureAuthorization(HttpSecurity http) throws Exception {
http.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/public/**").permitAll()
.requestMatchers("/api/admin/**").hasRole("ADMIN")
.anyRequest().authenticated()
);
}
}Ver ejemplo completo en joko_backend_starter_kit
# Preparar BD de test
./scripts/updater seed src/main/resources/db/sql/seed-test.sql
# Opción 1: Usar script de ayuda
./publish.sh test
# Opción 2: Usar Maven Wrapper
./mvnw test
# Opción 3: Test específico
./mvnw test -Dtest=TokenServiceTest
# Con Maven global
mvn test -Dtest=TokenServiceTest- Token creation y parsing
- Refresh token flow
- Token revocation
- Security filters
- JWT signature verification
# JWT Secret (mínimo 32 caracteres, 256 bits)
JWT_SECRET=tu-secreto-muy-largo-y-aleatorio-importante
# Base de datos
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/joko_db
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=passwordVer application.properties.example para todas las opciones disponibles:
- Tiempo de vida de tokens por perfil
- Modo de almacenamiento de secret (BD vs FILE)
- Habilitación de autenticación
- Rutas públicas (sin autenticación)
- Configuración de CORS
Todas las tablas en schema joko_security:
security_profile- Configuración de tiempos de vidakeychain- Claves secretas para firma JWTtoken- Refresh tokens activos/revocadosprincipal_session- Sesiones de usuarioaudit_session- Auditoría de accesosseed- Semillas para OTP/TOTPconsumer_api- Registro de consumidores API
El proyecto usa Liquibase para migraciones automáticas.
# Crear BD desde cero
./scripts/updater fresh
# Actualizar schema existente
./scripts/updater update
# Generar diff SQL
mvn liquibase:diff✅ JWT Algorithm Verification (prevent "none" attack) ✅ JWT Signature Validation ✅ Token Expiration Enforcement ✅ Secret Key Rotation Support ✅ HTTPS enforcement (configurable) ✅ CORS configuration ✅ SQL Injection prevention (Prepared Statements) ✅ Dependency vulnerability scanning (OWASP Dependency Check)
# Con Maven Wrapper (recomendado)
./mvnw org.owasp:dependency-check-maven:check
# O con Maven global
mvn org.owasp:dependency-check-maven:checkReportes en target/dependency-check-report.html
- docs/INTEGRATION_GUIDE.md - Guía completa de integración en otro proyecto
- docs/PACKAGING_GUIDE.md - Guía completa de empaquetado y publicación
- docs/GITHUB_ACTIONS.md - Guía completa de CI/CD con GitHub Actions
- CLAUDE.md - Documentación técnica completa del proyecto
- CHANGELOG.md - Historial de versiones
./publish.sh local # Compilar e instalar localmente
./publish.sh test # Ejecutar tests
./publish.sh github # Publicar en GitHub Packages
./publish.sh version X.Y.Z # Actualizar versión- Spring Boot: 3.3.1
- Spring Security: 6.x (incluido en Spring Boot 3.3.1)
- Java: 17
- JJWT: 0.12.6
- PostgreSQL: 9.4+ (desarrollo y producción)
- H2: 2.2.224 (testing)
- Liquibase: Migraciones de BD
- Maven: 3.8+
Seguimos Semantic Versioning:
- MAJOR (2.x.x): Cambios incompatibles (breaking changes)
- MINOR (x.1.x): Nueva funcionalidad compatible
- PATCH (x.x.1): Bug fixes
Versión actual: 2.0.0
[Especificar licencia - MIT/Apache/etc]
- Fork del proyecto
- Crear feature branch (
git checkout -b feature/nueva-funcionalidad) - Commit cambios (
git commit -m 'feat: Agregar nueva funcionalidad') - Push al branch (
git push origin feature/nueva-funcionalidad) - Abrir Pull Request
- Issues: https://github.com/jokoframework/security/issues
- Documentación: Ver archivos .md en el repositorio
- Ejemplo de uso: joko_backend_starter_kit
- Soporte para Redis como storage alternativo
- GitHub Actions CI/CD automatizado
- Docker compose para desarrollo
- Métricas y monitoring con Micrometer
- Documentación Swagger/OpenAPI mejorada
Última actualización: 2024-12-22 Branch actual: feature/modular-refactor Versión: 2.0.0-SNAPSHOT