JWT con Spring Security y Spring Boot: emitir y validar tokens
Cómo proteger una API con JWT en Spring Boot 4 y Spring Security 7 sin librerías externas: emitir el token, validarlo, roles con scope y errores reales.
En resumen: con Spring Security no necesitas librerías externas para JWT. El starter
spring-boot-starter-oauth2-resource-servervalida los tokens (.oauth2ResourceServer(o -> o.jwt(...))) yNimbusJwtEncoderlos firma. Un endpoint/tokenautentica con usuario y contraseña y devuelve un JWT; el resto de la API exigeAuthorization: Bearer <token>. Escrito y probado con Spring Boot 4.1.2, Spring Security 7 y Java 21, con peticiones HTTP reales contra la aplicación arrancada.
Vídeo explicativo
Qué es un JWT
Un JSON Web Token son tres partes en Base64URL separadas por puntos: cabecera (algoritmo), payload (los claims: quién es, cuándo caduca, qué permisos tiene) y firma. El servidor no guarda sesiones: comprueba la firma y la fecha de caducidad en cada petición. Importante: el payload no está cifrado, solo firmado. Cualquiera puede leerlo; nadie puede cambiarlo sin invalidar la firma.
Dependencia
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
Incluye Spring Security y Nimbus JOSE, la librería con la que Spring firma y verifica los tokens.
Configuración
@Configuration
class SecurityConfig {
// En producción la clave viene de un secreto (variable de entorno, vault), nunca del código
@Bean
SecretKey jwtKey(@Value("${app.jwt.secret}") String secret) {
return new SecretKeySpec(secret.getBytes(), "HmacSHA256");
}
@Bean
JwtEncoder jwtEncoder(SecretKey key) {
return new NimbusJwtEncoder(new ImmutableSecret<>(key));
}
@Bean
JwtDecoder jwtDecoder(SecretKey key) {
return NimbusJwtDecoder.withSecretKey(key).macAlgorithm(MacAlgorithm.HS256).build();
}
// Cadena 1: solo /token, autenticada con usuario y contraseña
@Bean
@Order(1)
SecurityFilterChain tokenChain(HttpSecurity http) throws Exception {
http.securityMatcher("/token")
.authorizeHttpRequests(a -> a.anyRequest().authenticated())
.httpBasic(Customizer.withDefaults())
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.csrf(c -> c.disable());
return http.build();
}
// Cadena 2: el resto de la API, autenticada con el JWT de la cabecera Authorization: Bearer
@Bean
@Order(2)
SecurityFilterChain apiChain(HttpSecurity http) throws Exception {
http.authorizeHttpRequests(a -> a
.requestMatchers("/api/admin/**").hasAuthority("SCOPE_ADMIN")
.anyRequest().authenticated())
.oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.csrf(c -> c.disable());
return http.build();
}
@Bean
PasswordEncoder passwordEncoder() {
return PasswordEncoderFactories.createDelegatingPasswordEncoder();
}
@Bean
UserDetailsService usuarios(PasswordEncoder encoder) {
return new InMemoryUserDetailsManager(
User.withUsername("ana").password(encoder.encode("ana123")).authorities("USER").build(),
User.withUsername("admin").password(encoder.encode("admin123")).authorities("USER", "ADMIN").build());
}
}
app.jwt.secret=${JWT_SECRET:clave-de-desarrollo-de-al-menos-32-bytes!!}
Con HS256 la clave debe tener al menos 32 bytes (256 bits). Los usuarios en memoria son para el ejemplo: en una aplicación real vienen de la base de datos.
Emitir el token
@RestController
class TokenController {
private final JwtEncoder encoder;
TokenController(JwtEncoder encoder) {
this.encoder = encoder;
}
@PostMapping("/token")
String token(Authentication auth) {
Instant ahora = Instant.now();
String scope = auth.getAuthorities().stream()
.map(GrantedAuthority::getAuthority)
.filter(a -> !a.startsWith("FACTOR_")) // Spring Security 7 añade FACTOR_PASSWORD al autenticar
.collect(Collectors.joining(" "));
JwtClaimsSet claims = JwtClaimsSet.builder()
.issuer("codeja-demo")
.issuedAt(ahora)
.expiresAt(ahora.plus(15, ChronoUnit.MINUTES))
.subject(auth.getName())
.claim("scope", scope) // Spring lo convierte en autoridades SCOPE_USER, SCOPE_ADMIN
.build();
JwsHeader header = JwsHeader.with(MacAlgorithm.HS256).build();
return encoder.encode(JwtEncoderParameters.from(header, claims)).getTokenValue();
}
}
@RestController
class ApiController {
@GetMapping("/api/perfil")
String perfil(Authentication auth) {
Jwt jwt = (Jwt) auth.getPrincipal();
return "Hola, " + jwt.getSubject() + " (expira " + jwt.getExpiresAt() + ")";
}
@GetMapping("/api/admin/informe")
String informe() {
return "Informe solo para administradores";
}
}
Detalle de Spring Security 7: al autenticar con contraseña añade la autoridad FACTOR_PASSWORD (es la base de la autenticación multifactor). Si no la filtras, acaba dentro del token como un permiso más; nos pasó en la primera versión del ejemplo.
Lo que pasó al probarlo
Arrancamos la aplicación en un puerto aleatorio y lanzamos peticiones reales con java.net.http.HttpClient:
Token (3 partes separadas por puntos): 3
Cabecera: {"alg":"HS256"}
Payload: {"iss":"codeja-demo","sub":"ana","exp":1794828031,"iat":1794827131,"scope":"USER"}
GET /api/perfil sin token -> 401
WWW-Authenticate: Bearer resource_metadata="http://localhost:65180/.well-known/oauth-protected-resource"
GET /api/perfil con token -> 200 Hola, ana (expira 2026-11-16T11:19:49Z)
GET /api/admin/informe con token -> 403
WWW-Authenticate: Bearer error="insufficient_scope", ...
GET /api/admin/informe con token -> 200 Informe solo para administradores (token de admin)
GET /api/perfil con token -> 401 (firma manipulada)
WWW-Authenticate: Bearer error="invalid_token", error_description="... Signed JWT rejected: Invalid signature"
Los cinco casos que importan: sin token 401, token válido 200, token válido sin permiso 403, permiso correcto 200 y token manipulado 401. Cambiar un solo carácter de la firma basta para que el token se rechace.
Desde un cliente
TOKEN=$(curl -s -X POST -u ana:ana123 http://localhost:8080/token)
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/perfil
Buenas prácticas
- Caducidad corta (minutos) y, si necesitas sesiones largas, refresh tokens guardados en servidor que puedas revocar.
- No metas datos sensibles en el payload: se lee con un simple Base64.
- La clave fuera del código y distinta por entorno. Si la cambias, todos los tokens anteriores dejan de valer.
- HTTPS siempre: quien intercepta un token puede usarlo hasta que caduque.
- Si tienes un proveedor de identidad (Keycloak, Auth0, Cognito), no emitas tokens tú: configura
spring.security.oauth2.resourceserver.jwt.issuer-uriy Spring valida con sus claves públicas (RS256). Es lo que cubrimos en JWS y JWK con Spring Security.
Preguntas frecuentes
¿Por qué no uso la librería jjwt?
Puedes, pero Spring Security ya trae todo lo necesario para firmar y validar, integrado con su cadena de filtros y sus errores estándar (WWW-Authenticate). Menos código propio y menos dependencias.
¿Cómo cierro sesión con JWT?
Un JWT no se puede «desactivar» antes de caducar sin guardar estado en el servidor. Por eso se usan caducidades cortas y una lista de revocación o refresh tokens para los casos que lo necesiten.
¿Cuál es la diferencia entre 401 y 403?
401: no sabemos quién eres (sin token o token inválido). 403: sabemos quién eres, pero no tienes permiso.
¿Y la autenticación Basic?
Envía usuario y contraseña en cada petición. Es más simple y válida para APIs internas con HTTPS; la tienes en Spring Security con Basic Auth.
Sigue aprendiendo
Autenticación, autorización por roles, OAuth2 y JWT se trabajan de principio a fin en el curso de Spring Boot Security. Si vienes de cero, empieza por crear una API REST con Spring Boot.
Newsletter Semanal de Java
Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.
Sin spam. Cancela cuando quieras.