Joko Security

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.

Características Principales

✅ 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

Arquitectura Multi-Módulo

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

Inicio Rápido

1. Como Dependencia en otro Proyecto

Maven

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>

Gradle

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.

Configurar application.yml

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 tabla security_profile.

Ver docs/INTEGRATION_GUIDE.md para guía completa de integración.

2. Desarrollo Local (Compilar desde código fuente)

Pre-requisitos

Java 17
Maven 3.8+
PostgreSQL 9.4+ (o H2 para testing)

Clonar y compilar

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 install

Recomendación: Usar ./mvnw (Maven Wrapper) para garantizar consistencia de versiones.

Configurar entorno de desarrollo

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:run

La aplicación estará disponible en http://localhost:8080/security

Publicar como Dependencia

Publicar en GitHub Packages

# 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

Publicar en Artifactory Interno

# 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 release

Ver docs/PACKAGING_GUIDE.md y docs/ARTIFACTORY.md para instrucciones detalladas.

Conceptos Clave

Tokens

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)

Security Profiles

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

Flujo de Autenticación

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

Personalización

Dos interfaces principales para implementar:

JokoAuthenticationManager

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");
    }
}

JokoAuthorizationManager

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

Testing

Ejecutar tests

# 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

Coverage de tests

Token creation y parsing
Refresh token flow
Token revocation
Security filters
JWT signature verification

Configuración

Variables de entorno requeridas

# 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=password

Opciones de configuración avanzadas

Ver 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

Base de Datos

Esquema

Todas las tablas en schema joko_security:

security_profile - Configuración de tiempos de vida
keychain - Claves secretas para firma JWT
token - Refresh tokens activos/revocados
principal_session - Sesiones de usuario
audit_session - Auditoría de accesos
seed - Semillas para OTP/TOTP
consumer_api - Registro de consumidores API

Migraciones

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

Seguridad

Protecciones OWASP implementadas

✅ 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)

Ejecutar scan de vulnerabilidades

# Con Maven Wrapper (recomendado)
./mvnw org.owasp:dependency-check-maven:check

# O con Maven global
mvn org.owasp:dependency-check-maven:check

Reportes en target/dependency-check-report.html

Documentación Adicional

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

Scripts de Ayuda

./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

Stack Tecnológico

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+

Versionamiento

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

Licencia

[Especificar licencia - MIT/Apache/etc]

Contribuir

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

Soporte

Issues: https://github.com/jokoframework/security/issues
Documentación: Ver archivos .md en el repositorio
Ejemplo de uso: joko_backend_starter_kit

Roadmap

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

Name		Name	Last commit message	Last commit date
Latest commit History 184 Commits
.github/workflows		.github/workflows
.mvn/wrapper		.mvn/wrapper
database-templates/flyway		database-templates/flyway
db		db
development		development
docs		docs
joko-security-autoconfigure		joko-security-autoconfigure
joko-security-core		joko-security-core
joko-security-starter		joko-security-starter
joko-security-storage-postgres		joko-security-storage-postgres
joko-security-web		joko-security-web
plan/joko-upgrade		plan/joko-upgrade
scripts		scripts
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
.travis.yml		.travis.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
dependency-check-suppressions.xml		dependency-check-suppressions.xml
mvn.sh		mvn.sh
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml
publish-artifactory.sh		publish-artifactory.sh
publish.sh		publish.sh
settings.xml.example		settings.xml.example
test.sh		test.sh

License

sodep/joko-security-interfisa

Folders and files

Latest commit

History

Repository files navigation