Spring Security custom JSON authentication failure response

This article details how to customize the authentication entry point (AuthenticationEntryPoint) in Spring Security to return a formatted JSON error response instead of the default HTML page when the user accesses protected resources without authentication. By configuring `CustomAuthenticationEntryPoint` and writing JSON data directly to `HttpServletResponse`, developers can provide a more friendly and consistent error handling mechanism for API clients.

When building a RESTful API, a unified error response format is crucial. When Spring Security handles unauthenticated requests, it will return an error page in HTML format (such as HTTP Status 401 Unauthorized) by default. This may work for browser clients, but for API clients that require responses in JSON format, this default behavior is not ideal. This tutorial will guide you on how to solve this problem by customizing the AuthenticationEntryPoint to return a structured JSON error message.

Problem with default authentication failure response

When Spring Security detects an unauthenticated request trying to access a protected resource, it triggers an AuthenticationEntryPoint. By default, this usually results in the browser redirecting to the login page or returning a 401 Unauthorized response containing HTML content. For API consumers, the expected response is usually in JSON format like this:

 {
    "errors": [
        {
            "status": "401",
            "title": "UNAUTHORIZED",
            "detail": "Authentication failed or missing authentication credentials"
        }
    ]
}

What you actually receive may be:

 


    <title>HTTP Status 401 – Unauthorized</title>
    <!-- ... style... -->


    <h1>HTTP Status 401 – Unauthorized</h1>

Obviously, this HTML response is not suitable for automated parsing by API clients.

Custom AuthenticationEntryPoint

To implement an authentication failure response in JSON format, we need to create a custom AuthenticationEntryPoint implementation. This class will be responsible for writing the JSON data we expect directly to HttpServletResponse when authentication fails.

First, define your custom AuthenticationEntryPoint:

 import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.stereotype.Component;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Collections;
import java.util.Map;

@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) throws IOException {

        //Set the response content type to JSON
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        //Set the HTTP status code to 401 Unauthorized
        response.setStatus(HttpStatus.UNAUTHORIZED.value());

        // Optional: Add WWW-Authenticate header, necessary for Basic authentication response.addHeader("WWW-Authenticate", "Basic realm=\"Realm\"");

        // Construct JSON error body Map<string object> errorDetails = Map.of(
            "status", String.valueOf(HttpStatus.UNAUTHORIZED.value()),
            "title", HttpStatus.UNAUTHORIZED.name(),
            "detail", authException.getMessage() != null ? authException.getMessage() : "Authentication failed or authentication credentials are missing"
        );
        Map<string object> errorResponse = Collections.singletonMap("errors", Collections.singletonList(errorDetails));

        //Write JSON into the response body try (PrintWriter writer = response.getWriter()) {
            objectMapper.writeValue(writer, errorResponse);
        }
    }
}</string></string>

Code analysis:

1. @Component : Register CustomAuthenticationEntryPoint as a Spring Bean for injection in Spring Security configuration.
2. Commence method : This is the core method of the AuthenticationEntryPoint interface and is called when an unauthenticated user attempts to access a protected resource.
3. response.setContentType(MediaType.APPLICATION_JSON_VALUE) : The key step is to set the Content-Type of the response to application/json to inform the client that JSON data is returned.
4. response.setStatus(HttpStatus.UNAUTHORIZED.value()) : Set the HTTP status code to 401, indicating not authenticated.
5. response.addHeader("WWW-Authenticate", "Basic realm=\"Realm\"") : If you are using HTTP Basic authentication, this header is required and will prompt the client to provide authentication information.
6. Build JSON body : ObjectMapper is used here to serialize Java Map objects into JSON strings. This method is more robust and recommended than manually concatenating strings. You can customize the JSON structure and error information according to actual needs.
7. response.getWriter() : Get the PrintWriter object, through which the generated JSON string is written into the response body.

Configure Spring Security to use a custom EntryPoint

Next, you need to register and use this custom AuthenticationEntryPoint in Spring Security's configuration class.

 import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

    private final CustomAuthenticationEntryPoint customAuthenticationEntryPoint;

    // Inject custom AuthenticationEntryPoint through the constructor
    public SecurityConfiguration(CustomAuthenticationEntryPoint customAuthenticationEntryPoint) {
        this.customAuthenticationEntryPoint = customAuthenticationEntryPoint;
    }

    @Override
    protected void configure(HttpSecurity httpSecurity) throws Exception {
        httpSecurity
                .csrf().disable() // Disable CSRF protection, usually API does not require .authorizeRequests()
                .antMatchers(HttpMethod.GET, "/public/**").permitAll() // Allow GET requests to access the /public/** path.anyRequest().authenticated() // All other requests require authentication.and()
                .httpBasic() // Enable HTTP Basic authentication.and()
                .exceptionHandling()
                .authenticationEntryPoint(customAuthenticationEntryPoint); // Specify a custom authentication entry point}
}

Configuration analysis:

1. @Configuration and @EnableWebSecurity : mark this as a Spring Security configuration class.
2. Constructor injection : Inject CustomAuthenticationEntryPoint into SecurityConfiguration.
3. httpSecurity.exceptionHandling().authenticationEntryPoint(customAuthenticationEntryPoint) : This is the core configuration, telling Spring Security to use our custom customAuthenticationEntryPoint to handle when authentication fails.
4. httpBasic() : Enable HTTP Basic authentication. If your API uses other authentication methods (such as JWT), this part of the configuration will be different.
5. authorizeRequests() : Defines which requests require authentication and which can be publicly accessed.

Test custom responses

In order to verify that our custom AuthenticationEntryPoint works as expected, we can write an integration test. Spring Boot Test and MockMvc are used here to simulate HTTP requests.

 package com.example.security.custom.entrypoint;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.context.annotation.Import;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest // Only load beans related to the Web layer
@Import({SecurityConfiguration.class, CustomAuthenticationEntryPoint.class}) // Import Security configuration and EntryPoint
class SecurityCustomEntrypointApplicationTests {

  @Autowired
  private MockMvc mvc;

  @Test
  void testUnauthorizedAccessReturnsJson() throws Exception {
    mvc
        .perform(post("/somewhere")) // Simulate an unauthenticated POST request to a protected path. andDo(print()) // Print request and response details for easy debugging. andExpectAll(
            status().isUnauthorized(), // Expect HTTP status code to be 401
            header().exists("WWW-Authenticate"), // Expect WWW-Authenticate in the response header
            jsonPath("$.errors[0].detail").exists(), // Expect the JSON path errors[0].detail to exist jsonPath("$.errors[0].title").value("UNAUTHORIZED"), // Expect the value of the JSON path errors[0].title to be "UNAUTHORIZED"
            jsonPath("$.errors[0].status").value(401) // Expect the value of JSON path errors[0].status to be 401
        );
  }
}

Test analysis:

1. @WebMvcTest : Focus on testing Spring MVC components and will not start the complete Spring Boot application.
2. @Import : Explicitly import SecurityConfiguration and CustomAuthenticationEntryPoint to ensure that the Spring Security configuration takes effect in the test environment.
3. MockMvc : used to simulate HTTP requests and verify responses.
4. perform(post("/somewhere")) : Sends a POST request to /somewhere, assuming this is a protected path and no authentication credentials are provided.
5. andExpectAll(...) : Use multiple assertions to validate the response:
   • status().isUnauthorized(): Check whether the HTTP status code is 401.
   • header().exists("WWW-Authenticate"): Check whether the WWW-Authenticate header exists.
   • jsonPath(...): Use JSONPath expressions to verify the content and structure of the JSON response body.

Things to note and best practices

1. Use ObjectMapper : In actual projects, it is strongly recommended to use Jackson's ObjectMapper (or other JSON libraries such as Gson) to serialize Java objects to JSON strings instead of manually splicing strings. This avoids formatting errors and allows for better handling of complex objects.
2. Internationalization of error information : In actual applications, error information (such as the detail field) may need to support internationalization. You can inject a MessageSource into CustomAuthenticationEntryPoint to obtain localized error information.
3. AccessDeniedHandler : AuthenticationEntryPoint only handles access from unauthenticated users. If the user is authenticated but does not have permission to access a resource (i.e. authorization fails), you need to implement AccessDeniedHandler to provide a similar JSON error response.
4. Logging : Add appropriate logging in the commence method to track authentication failure events in production.
5. Custom error codes : In addition to HTTP status codes, you can define your own business error codes in the JSON response to provide more fine-grained error classification.

Summarize

By customizing Spring Security's AuthenticationEntryPoint, you can easily replace the default HTML authentication failure response with a structured JSON response. This is critical for building modern RESTful APIs, ensuring that API clients receive consistent and easy-to-parse error messages, thereby improving user experience and system maintainability. Combined with ObjectMapper and rigorous testing, you can build a robust and professional API error handling mechanism.

The above is the detailed content of Spring Security custom JSON authentication failure response. For more information, please follow other related articles on the PHP Chinese website!