Artículo

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-security toda la aplicación queda protegida por defecto. Define un SecurityFilterChain con .httpBasic(...) para autenticar con usuario y contraseña en la cabecera Authorization, reglas por URL con .requestMatchers(...) y un PasswordEncoder (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 autoridad ROLE_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: Basic es 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 BasicJWT
Qué viaja en cada peticiónUsuario y contraseñaUn token firmado con caducidad
ComprobaciónConsulta el usuario y verifica el hash cada vezVerifica la firma, sin consultar
Revocar accesoInmediato (cambias la contraseña)Hay que esperar a que caduque o mantener una lista
Uso típicoHerramientas internas, servicios entre sí, prototiposAPIs 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.

spring security basic auth spring boot autenticación autorización bcrypt

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.

Compartir artículo