Skip to main content

🛡️ Alpura Back Java Lib Security v2.3

Manual de implementación de la librería común de seguridad y autenticación OAuth2 / JWT para microservicios Spring Boot (com.alpura:back-java-lib-security:2.3).

📦 Requisitos​

  • Java JDK: 21 (Temurin LTS)
  • Spring Boot: 3.4.4 o superior
  • Alpura BOM: 1.0.4

⚙️ Instalación​

Opción A: Heredando versión desde Alpura BOM 1.0.4 (RECOMENDADO)​

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alpura</groupId>
            <artifactId>bom</artifactId>
            <version>1.0.4</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.alpura</groupId>
        <artifactId>back-java-lib-security</artifactId>
    </dependency>
</dependencies>

Opción B: Uso directo (Standalone)​

<dependency>
    <groupId>com.alpura</groupId>
    <artifactId>back-java-lib-security</artifactId>
    <version>2.3</version>
</dependency>

Gradle: implementation 'com.alpura:back-java-lib-security:2.3'

🛠️ Configuración (YAML)​

1. Configuración Estándar Resource Server (Keycloak / OAuth2)​

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://hub-uat-login.alpura.com/auth/realms/Alpura
          jwk-set-uri: https://hub-uat-login.alpura.com/auth/realms/Alpura/protocol/openid-connect/certs

alpuraSecurity:
  evaluateRoles: false
  disableSecurity: false # Define si se deshabilita la seguridad (ej. pruebas locales)

2. Configuración para Adquisición / Propagación de Tokens OAuth2​

v2.3 incluye utilidades (OAuthTokenClient, OAuthTokenServiceImpl, TokenRelayInterceptor) para solicitar tokens OAuth2 automáticamente a un IDP mediante client_credentials o password grant:

security:
  oauth2:
    token:
      url: https://hub-uat-login.alpura.com/auth/realms/Alpura/protocol/openid-connect/token
      clientId: MobileApp
      clientSecret: KkW4Z6Y28IhMqpjvFCN4jS5MTO253Sj5
      grantType: client_credentials # o 'password'
      userName: ""
      password: ""

🧭 Escaneo de Componentes​

Asegúrate de registrar el paquete de seguridad en @ComponentScan:

@SpringBootApplication
@ComponentScan({
  "com.alpura.security",
  "com.alpura.utilities"
})
public class ExApplication {
  public static void main(String[] args) {
    SpringApplication.run(ExApplication.class, args);
  }
}

🚀 Características y Rutas Excluidas​

La librería v2.3 configura automáticamente las siguientes reglas en la cadena de seguridad (SecurityFilterChain):

  1. Rutas Públicas Permitidas Automáticamente:
    • Endpoints de monitoreo Actuator: /actuator/**
    • Documentación interactiva OpenAPI / Swagger UI: /, /v3/api-docs/**, /swagger-ui.html, /swagger-ui/**
  2. Modo Bypass: Al establecer alpuraSecurity.disableSecurity: true, la aplicación permitirá todas las solicitudes HTTP (/**) sin exigir token JWT (ideal para pruebas offline).
  3. Conversión de Roles: JwtAuthenticationConverter mapea los roles del claim realm_access añadiendo el prefijo ROLE_.

🔧 Extracción de Contexto y Token en Controlador​

Extiende tus controladores de BaseController (de back-java-lib-common-utilities):

@RestController
@RequestMapping("/api/v1/mi-modulo")
public class MiController extends BaseController {

    @GetMapping("/datos")
    public ResponseEntity<SingleResponseVO<MyData>> getDatos() {
        RequestVO<Void> request = getRequest(); // Extrae contexto de usuario y token
        // ...
        return ResponseEntity.ok(response);
    }
}