Errores de seguridad, 401 frente a 403

401 Unauthorized significa “no sé quién eres, identifícate”. 403 Forbidden significa “sé quién eres y no puedes”. El nombre de 401 es un error histórico del estándar HTTP: debería llamarse Unauthenticated. Spring Security decide entre ambos en un único sitio.

Analogía

La recepción de una oficina

La recepcionista no te pregunta el nombre por gusto: lo hace porque no te conoce. Si ya te conoce, no tiene sentido pedirte el DNI otra vez: simplemente te dice que no.

En el mundo realEn tu sistema

"Perdone, ¿quién es usted?"401: falta identidad (o es inválida)

"Le conozco, pero a esta planta no puede subir"403: identidad clara, permiso insuficiente

La recepcionista apunta a qué planta ibasRequestCache: recordar la URL para volver tras el login

Cómo decide Spring

Sube una excepción de seguridadExceptionTranslationFilter · catch

AuthenticationException

401entry point → pide credencialesguarda la petición (RequestCache)

AccessDeniedException

¿El usuario es anónimo?

sí

401entry point → pide credenciales

no

403access denied handler

La pregunta clave no es qué excepción se lanzó, sino si había alguien autenticado.

ExceptionTranslationFilter envuelve el resto de la cadena (incluido tu controlador) en un try/catch. Simplificado:

try {
    chain.doFilter(request, response);
} catch (AuthenticationException ex) {
    startAuthentication(request, response, ex);            // → 401 (entry point)
} catch (AccessDeniedException ex) {
    if (isAnonymous(currentAuthentication())) {
        startAuthentication(request, response, ex);        // anónimo → 401: que se identifique
    } else {
        accessDeniedHandler.handle(request, response, ex); // autenticado → 403
    }
}

“Iniciar la autenticación” guarda primero la petición en el RequestCache: en apps con formulario, tras el login te devuelve a la URL que intentabas abrir. En una API stateless no sirve de nada; puedes desactivarlo con http.requestCache(c -> c.disable()).

Idea clave

Un anónimo que choca con AccessDeniedException recibe 401, no 403: lo útil es pedirle que se identifique. Por eso casi todos tus 401 vienen de AuthorizationFilter, no de un filtro de autenticación.

Qué respuesta sale por defecto

Mecanismo activo	AuthenticationEntryPoint por defecto	Respuesta
formLogin	LoginUrlAuthenticationEntryPoint	302 a /login
httpBasic	BasicAuthenticationEntryPoint	401 + WWW-Authenticate: Basic realm="Realm"
oauth2ResourceServer	BearerTokenAuthenticationEntryPoint	401 + WWW-Authenticate: Bearer … con el motivo
Ninguno	Http403ForbiddenEntryPoint	403, aunque sea falta de autenticación

Si activas varios, Spring elige según la cabecera Accept y el tipo de petición. Por eso un navegador ve el formulario de login y curl ve un 401.

Tres trampas que cuestan horas

Trampa común

El endpoint /error protegido

Cuando tu controlador lanza una excepción cualquiera (por ejemplo, un 400 de validación), Spring Boot hace un forward interno a /error. Ese forward vuelve a pasar por la cadena de seguridad. Si /error exige autenticación, tu 400 se convierte en un 401 o 403 sin cuerpo. Solución: .requestMatchers("/error").permitAll().

Trampa común

Un @ControllerAdvice que se come los 403

Un @PreAuthorize que falla lanza AccessDeniedException dentro de Spring MVC. Si tienes un @ExceptionHandler(Exception.class) genérico, la atrapa antes de que llegue a ExceptionTranslationFilter y devuelve un 500. Relanza las excepciones de seguridad:

@ExceptionHandler(Exception.class)
ProblemDetail unexpected(Exception e) throws Exception {
    if (e instanceof AccessDeniedException || e instanceof AuthenticationException) {
        throw e;                               // que las gestione Spring Security
    }
    log.error("Error inesperado", e);
    return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, "Error interno");
}

Trampa común

Las excepciones de los filtros no llegan al @ControllerAdvice

Un error en un filtro de autenticación ocurre antes del DispatcherServlet: ningún @ControllerAdvice lo verá. Ahí solo el AuthenticationEntryPoint (o un AccessDeniedHandler) puede dar formato a la respuesta.

Respuestas JSON con ProblemDetail

Una API debería responder sus errores en el formato estándar RFC 9457 (application/problem+json), también los de seguridad:

ProblemAuthenticationEntryPoint.java

@Component
class ProblemAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final JsonMapper json;   // tools.jackson.databind.json.JsonMapper (Jackson 3, Spring Boot 4)

    ProblemAuthenticationEntryPoint(JsonMapper json) {
        this.json = json;
    }

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException ex) throws IOException {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNAUTHORIZED, "Necesitas autenticarte para acceder a este recurso");
        problem.setInstance(URI.create(request.getRequestURI()));

        response.setStatus(HttpStatus.UNAUTHORIZED.value());
        response.setHeader(HttpHeaders.WWW_AUTHENTICATE, "Basic realm=\"notes\"");
        response.setContentType(MediaType.APPLICATION_PROBLEM_JSON_VALUE);
        json.writeValue(response.getOutputStream(), problem);
    }
}

El AccessDeniedHandler es igual, con handle(...) y HttpStatus.FORBIDDEN. Se registran así (Basic tiene su propio entry point, que también hay que sustituir):

SecurityConfig.java

http
    .authorizeHttpRequests(auth -> auth
        .requestMatchers("/error").permitAll()
        .anyRequest().authenticated())
    .httpBasic(basic -> basic.authenticationEntryPoint(entryPoint))
    .exceptionHandling(ex -> ex
        .authenticationEntryPoint(entryPoint)
        .accessDeniedHandler(deniedHandler));

Novedad de la 7.0: exceptionHandling permite asociar un manejador a una authority que falta con defaultDeniedHandlerForMissingAuthority(...), por ejemplo para redirigir al segundo factor cuando falta FACTOR_OTT (lo verás en Spring Security 7).

Idea clave

No pongas en el cuerpo del error por qué falló la autenticación (“el usuario no existe”, “token caducado hace 3 minutos”). Esa información es para tu log, no para el cliente. Un mensaje genérico y el código correcto bastan.

Mini lab · 25 min

Errores que una API puede consumir

Marcar como completado

Objetivo: Que todos los errores de seguridad de /api/** respondan application/problem+json, sin romper los errores de validación.

1. Implementa ProblemAuthenticationEntryPoint y un ProblemAccessDeniedHandler equivalente.
2. Regístralos en la cadena de la API, junto con .requestMatchers("/error").permitAll().
3. Prueba los tres casos:

curl -i http://localhost:8080/api/notes                                  # sin credenciales
curl -i -u ana:contraseña-incorrecta http://localhost:8080/api/notes     # credenciales malas
curl -i -u ana:ana-password-123 http://localhost:8080/api/admin/stats    # sin permiso

4. Añade un @RestControllerAdvice con @ExceptionHandler(Exception.class) que devuelva 500, pon @PreAuthorize("hasRole('ADMIN')") en el método de /api/admin/stats (necesitas @EnableMethodSecurity) y repite la tercera petición.

Preguntas:

• ¿Las respuestas a “sin credenciales” y “credenciales malas” son distintas para el cliente? ¿Deberían serlo?
• En el paso 4, ¿qué código recibes y por qué? ¿Cómo lo corriges?
• Quita temporalmente /error del permitAll y envía un JSON inválido a POST /api/auth/register. ¿Qué código recibes y por qué no es 400?

Pista

Para la última pregunta: ¿qué petición hace Spring Boot internamente cuando tu controlador falla, y con qué usuario llega a la cadena?

Mostrar respuestaOcultar respuesta

• Ambas dan 401 con el mismo ProblemDetail. Es lo correcto: distinguirlas solo ayuda a un atacante. El motivo exacto está en el log TRACE.
• Recibes 500: el @ExceptionHandler(Exception.class) atrapa la AccessDeniedException de @PreAuthorize antes que Spring Security. Se corrige relanzando AccessDeniedException y AuthenticationException en el handler genérico (o con handlers específicos que devuelvan 403).
• Recibes 401 (o 403). El 400 de validación provoca un forward a /error, que vuelve a pasar por la cadena; como la petición a /error no es pública, la regla de autorización la rechaza y tu 400 se pierde. Con /error en permitAll vuelves a ver el 400 correcto.

En resumen

• ExceptionTranslationFilter traduce: AuthenticationException → 401; AccessDeniedException → 401 si eres anónimo, 403 si no.
• Cada mecanismo trae su AuthenticationEntryPoint; httpBasic necesita el suyo propio.
• Deja /error en permitAll, no te tragues las excepciones de seguridad en @ControllerAdvice.
• Responde con ProblemDetail y sin detalles que ayuden a un atacante.