1. Overview
Security plays a vital role in REST API development. An insecure REST API can provide direct access to sensitive data on back-end systems. So, organizations need to pay attention to API Security.
Spring Security provides various mechanisms to secure our REST APIs. One of them is API keys. An API key is a token that a client provides when invoking API calls.
In this tutorial, we’ll discuss the implementation of API key-based authentication in Spring Security.
2. REST API Security
Spring Security can be used to secure REST APIs. REST APIs are stateless. Thus, they shouldn’t use sessions or cookies. Instead, these should be secure using Basic authentication, API Keys, JWT, or OAuth2-based tokens.
2.1. Basic Authentication
Basic authentication is a simple authentication scheme. The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a Base64-encoded string username:password. Basic authentication is only considered secure with other security mechanisms such as HTTPS/SSL.
2.2. OAuth2
OAuth2 is the de facto standard for REST APIs security. It’s an open authentication and authorization standard that allows resource owners to give clients delegated access to private data via an access token.
2.3. API Keys
Some REST APIs use API keys for authentication. An API key is a token that identifies the API client to the API without referencing an actual user. The token can be sent in the query string or as a request header. Like Basic authentication, it’s possible to hide the key using SSL.
In this tutorial, we focus on implementing API Keys authentication using Spring Security.
3. Securing REST APIs with API Keys
In this section, we’ll create a Spring Boot application and secure it using API key-based authentication.
3.1. Maven Dependencies
Let’s start by declaring the spring-boot-starter-security dependency in our pom.xml:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
3.2. Creating Custom Filter
The idea is to get the HTTP API Key header from the request and then check the secret with our configuration. In this case, we need to add a custom Filter in the Spring Security configuration class.
We’ll start by implementing the GenericFilterBean. The GenericFilterBean is a simple javax.servlet.Filter implementation that is Spring-aware.
Let’s create the AuthenticationFilter class:
public class AuthenticationFilter extends GenericFilterBean {
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
throws IOException, ServletException {
try {
Authentication authentication = AuthenticationService.getAuthentication((HttpServletRequest) request);
SecurityContextHolder.getContext().setAuthentication(authentication);
} catch (Exception exp) {
HttpServletResponse httpResponse = (HttpServletResponse) response;
httpResponse.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
httpResponse.setContentType(MediaType.APPLICATION_JSON_VALUE);
PrintWriter writer = httpResponse.getWriter();
writer.print(exp.getMessage());
writer.flush();
writer.close();
}
filterChain.doFilter(request, response);
}
}
We only need to implement a doFilter() method. In this method, we evaluate the API Key header and set the resulting Authentication object into the current SecurityContext instance.
Then, the request is passed to the remaining filters for processing and then routed to DispatcherServlet and finally to our controller.
We delegate the evaluation of the API Key and constructing the Authentication object to the AuthenticationService class:
public class AuthenticationService {
private static final String AUTH_TOKEN_HEADER_NAME = "X-API-KEY";
private static final String AUTH_TOKEN = "Baeldung";
public static Authentication getAuthentication(HttpServletRequest request) {
String apiKey = request.getHeader(AUTH_TOKEN_HEADER_NAME);
if (apiKey == null || !apiKey.equals(AUTH_TOKEN)) {
throw new BadCredentialsException("Invalid API Key");
}
return new ApiKeyAuthentication(apiKey, AuthorityUtils.NO_AUTHORITIES);
}
}
Here, we check whether the request contains the API Key header with a secret or not. If the header is null or isn’t equal to secret, we throw a BadCredentialsException. If the request has the header, it performs the authentication, adds the secret to the security context, and then passes the call to the next security filter. Our getAuthentication method is quite simple – we just compare the API Key header and secret with a static value.
To construct the Authentication object, we must use the same approach Spring Security typically uses to build the object on a standard authentication. So, let’s extend the AbstractAuthenticationToken class and manually trigger authentication.
3.3. Extending AbstractAuthenticationToken
To successfully implement authentication for our application, we need to convert the incoming API Key to an Authentication object such as an AbstractAuthenticationToken. The AbstractAuthenticationToken class implements the Authentication interface, representing the secret/principal for an authenticated request.
Let’s create the ApiKeyAuthentication class:
public class ApiKeyAuthentication extends AbstractAuthenticationToken {
private final String apiKey;
public ApiKeyAuthentication(String apiKey, Collection<? extends GrantedAuthority> authorities) {
super(authorities);
this.apiKey = apiKey;
setAuthenticated(true);
}
@Override
public Object getCredentials() {
return null;
}
@Override
public Object getPrincipal() {
return apiKey;
}
}
The ApiKeyAuthentication class is a type of AbstractAuthenticationToken object with the apiKey information obtained from the HTTP request. We use the setAuthenticated(true) method in the construction. As a result, the Authentication object contains apiKey and authenticated fields:
3.4. Security Config
We can register our custom filter programmatically by creating a SecurityFilterChain bean. In this case, we need to add the AuthenticationFilter before the UsernamePasswordAuthenticationFilter class using the addFilterBefore() method on an HttpSecurity instance.
Let’s create the SecurityConfig class:
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http.csrf(AbstractHttpConfigurer::disable)
.authorizeHttpRequests(authorizationManagerRequestMatcherRegistry -> authorizationManagerRequestMatcherRegistry.requestMatchers("/**").authenticated())
.httpBasic(Customizer.withDefaults())
.sessionManagement(httpSecuritySessionManagementConfigurer -> httpSecuritySessionManagementConfigurer.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.addFilterBefore(new AuthenticationFilter(), UsernamePasswordAuthenticationFilter.class);
return http.build();
}
}
Also, the session policy is set to STATELESS because we’ll use REST endpoints.
3.5. ResourceController
Last, we’ll create the ResourceController with a /home mapping:
@RestController
public class ResourceController {
@GetMapping("/home")
public String homeEndpoint() {
return "Baeldung !";
}
}
3.6. Disabling the Default Auto-Configuration
We need to discard the security auto-configuration. To do this, we exclude the SecurityAutoConfiguration and UserDetailsServiceAutoConfiguration classes:
@SpringBootApplication(exclude = {SecurityAutoConfiguration.class, UserDetailsServiceAutoConfiguration.class})
public class ApiKeySecretAuthApplication {
public static void main(String[] args) {
SpringApplication.run(ApiKeySecretAuthApplication.class, args);
}
}
Now, the application is ready to test.
4. Testing
We can use the curl command to consume the secured application.
First, let’s try to request the /home without providing any security credentials:
curl --location --request GET 'http://localhost:8080/home'
We get back the expected 401 Unauthorized.
Now let’s request the same resource, but provide the API Key and secret to access it as well:
curl --location --request GET 'http://localhost:8080/home' \
--header 'X-API-KEY: Baeldung'
As a result, the response from the server is 200 OK.
5. Conclusion
In this tutorial, we discussed the REST API security mechanisms. Then, we implemented Spring Security in our Spring Boot application to secure our REST API using the API Keys authentication mechanism.
As always, code samples can be found over on GitHub.
