Spring Security con autenticación Basic en Spring Boot
Cómo proteger una API con Spring Security y HTTP Basic en Spring Boot 4: usuarios, contraseñas con BCrypt, roles por URL y los códigos 401 y 403 reales.
En resumen: con
spring-boot-starter-securitytoda la aplicación queda protegida por defecto. Define unSecurityFilterChaincon.httpBasic(...)para autenticar con usuario y contraseña en la cabeceraAuthorization, reglas por URL con.requestMatchers(...)y unPasswordEncoder(BCrypt) para guardar las contraseñas cifradas. Resultado: sin credenciales 401, credenciales válidas sin permiso 403. Probado con Spring Boot 4.1.2, Spring Security 7 y peticiones HTTP reales.
Vídeo explicativo
Cómo funciona HTTP Basic
El cliente envía en cada petición la cabecera Authorization: Basic <base64(usuario:contraseña)>. Base64 no cifra nada: cualquiera que intercepte la petición lee la contraseña. Por eso Basic solo es aceptable sobre HTTPS. No hay sesiones ni tokens: se autentica en cada petición.
Dependencias
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
Solo con añadir el starter, Spring protege todos los endpoints y genera un usuario user con una contraseña aleatoria que imprime en el log al arrancar. Útil para probar; en cuanto defines tu configuración, desaparece.
Configuración
@Configuration
class SecurityConfig {
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/publico").permitAll()
.requestMatchers("/admin/**").hasRole("ADMIN")
.anyRequest().authenticated())
.httpBasic(Customizer.withDefaults())
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.csrf(csrf -> csrf.disable()); // API sin sesión ni formularios: no hay cookie que proteger
return http.build();
}
@Bean
PasswordEncoder passwordEncoder() {
return PasswordEncoderFactories.createDelegatingPasswordEncoder(); // BCrypt por defecto
}
@Bean
UserDetailsService usuarios(PasswordEncoder encoder) {
return new InMemoryUserDetailsManager(
User.withUsername("ana").password(encoder.encode("ana123")).roles("USER").build(),
User.withUsername("admin").password(encoder.encode("admin123")).roles("USER", "ADMIN").build());
}
}
@RestController
class DemoController {
@GetMapping("/publico")
String publico() {
return "Cualquiera puede ver esto";
}
@GetMapping("/perfil")
String perfil(Principal principal) {
return "Hola, " + principal.getName();
}
@GetMapping("/admin/panel")
String admin() {
return "Panel de administración";
}
}
Puntos clave:
- El orden de las reglas importa: se evalúan de arriba abajo y gana la primera que encaja.
anyRequest()siempre al final. hasRole("ADMIN")comprueba la autoridadROLE_ADMIN;.roles("ADMIN")al crear el usuario añade ese prefijo automáticamente.createDelegatingPasswordEncoder()guarda las contraseñas con BCrypt y un prefijo ({bcrypt}), lo que permite cambiar de algoritmo en el futuro sin romper las existentes.- CSRF desactivado porque es una API sin sesión que no usa cookies. Si tu aplicación usa formularios y sesión, déjalo activado.
Lo que pasó al probarlo
Arrancamos la aplicación y enviamos peticiones reales con java.net.http.HttpClient:
GET /publico (sin cabecera) -> 200 Cualquiera puede ver esto
GET /perfil (sin cabecera) -> 401
WWW-Authenticate: Basic realm="Realm", charset="UTF-8"
GET /perfil ana:mal -> 401
GET /perfil ana:ana123 -> 200 Hola, ana
GET /admin/panel ana:ana123 -> 403 {"timestamp":"...","status":403,"error":"Forbidden","path":"/admin/panel"}
GET /admin/panel admin:admin123 -> 200 Panel de administración
- 401 Unauthorized: no sabemos quién eres (sin credenciales o incorrectas). La cabecera
WWW-Authenticate: Basices la que hace que el navegador muestre la ventana de usuario y contraseña. - 403 Forbidden: sabemos quién eres, pero no tienes permiso.
Desde la terminal:
curl -u ana:ana123 http://localhost:8080/perfil
Usuarios desde la base de datos
InMemoryUserDetailsManager sirve para ejemplos. En una aplicación real implementas UserDetailsService y cargas el usuario con un repositorio JPA; el resto de la configuración no cambia:
@Bean
UserDetailsService usuarios(UsuarioRepository repo) {
return username -> repo.findByEmail(username)
.map(u -> User.withUsername(u.getEmail()).password(u.getPasswordHash()).roles(u.getRol()).build())
.orElseThrow(() -> new UsernameNotFoundException(username));
}
Guarda siempre el hash (encoder.encode(...) al registrar), nunca la contraseña. Más sobre el tema en hashing de contraseñas en Java.
¿Basic o JWT?
| HTTP Basic | JWT | |
|---|---|---|
| Qué viaja en cada petición | Usuario y contraseña | Un token firmado con caducidad |
| Comprobación | Consulta el usuario y verifica el hash cada vez | Verifica la firma, sin consultar |
| Revocar acceso | Inmediato (cambias la contraseña) | Hay que esperar a que caduque o mantener una lista |
| Uso típico | Herramientas internas, servicios entre sí, prototipos | APIs públicas, frontends, móviles |
Con JWT, la contraseña solo se envía una vez para obtener el token. Lo tienes en JWT con Spring Security.
Preguntas frecuentes
¿Por qué tarda cada petición unos milisegundos más?
Porque BCrypt es lento a propósito, para dificultar los ataques de fuerza bruta, y con Basic se verifica en cada petición. Para APIs con mucho tráfico, un token es más eficiente.
¿Cómo cierro sesión con Basic?
No hay sesión que cerrar: el navegador recuerda las credenciales hasta que se cierra. Por eso Basic no es buena opción para aplicaciones web con usuarios finales.
¿Puedo proteger métodos en lugar de URLs?
Sí, con @EnableMethodSecurity y @PreAuthorize("hasRole('ADMIN')") en los métodos de tus servicios.
Sigue aprendiendo
Autenticación con base de datos, roles, seguridad por método, OAuth2 y JWT se trabajan en el curso de Spring Boot Security. Para la API en sí, 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.