Understand Spring @EnableWebSecurity Annotation with Examples

Details: Written by Nam Ha Minh; Last Updated on 23 July 2024 | Print Email

In this post, I’d like to explain the syntax and usage of the @EnableWebSecurity annotation in Spring framework with some code examples. I will also address your doubts on weather this annotation is necessary in a Spring Boot application.

As the name implies, you can use this annotation to enable security (authentication and authorization) for a Java web application built on the Spring framework and Spring Security. The @EnableWebSecurity annotation is available for use if the Spring Security library is present in the classpath, or if one of the following starter dependencies is declared in a Spring Boot project:

spring-boot-starter-security
spring-boot-starter-oauth2-authorization-server
spring-boot-starter-oauth2-resource-server
spring-boot-starter-oauth2-client
… (any dependencies that depend on Spring Security)

This annotation can only be used at class level. Add this annotation to a @Configuration class and it will implement some basic security configurations to protect resource access, such as ignore security for all URLs starting with /resources/, allow access to all URLs starting with /public/, and require authentication for other URLs.

Let’s see an example. With Spring Security 5.x or older, add the @EnableWebSecurity to a configuration class that extends WebSecurityConfigurerAdapter as follows:

package net.codejava.security;

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

@Configuration
@EnableWebSecurity
public class AppSecurityConfig extends WebSecurityConfigurerAdapter {

	@Override
	public void configure(WebSecurity web) throws Exception {
		
		// override web security configurations...
		
	}
	
	@Override
	protected void configure(HttpSecurity http) throws Exception {
		
		// override HTTP security configurations...
	}

}

The purpose of using the @EnableWebSecurity annotation in this example is to enable web security with some default configurations and to additionally override web and HTTP security via the configure(WebSecurity) and configure(HttpSecurity) methods.

Below is another example with Spring Security 6.x or later:

package net.codejava;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.WebSecurityCustomizer;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class AppSecurityConfig   {
	

	@Bean
	SecurityFilterChain configure(HttpSecurity http) throws Exception {
		// override HTTP security configurations...
	}
	

	@Bean
	WebSecurityCustomizer configureWebSecurity() {
		// override web security configurations...
	}
}

In this example, the @EnableWebSecurity annotation provides some default security configurations, plus we can override by declaring two beans of type SecurityFilterChain and WebSecurityCustomizer.

1. Using @EnableWebSecurity in non-Spring Boot applications

If your project uses the plain Spring framework and Spring Security without Spring Boot, using this annotation is mandatory to enable and configure web security for your Spring applications. If you look deeper into the source code, you’ll see that the @EnableWebSecurity annotation imports the following classes:

WebSecurityConfiguration: creates the Spring Security filter chain and exposes necessary beans for web based security
SpringWebMvcImportSelector: conditionally imports the WebMvcSecurityConfiguration when the DispatcherServlet is present on the classpath
OAuth2ImportSelector: conditionally imports the OAuth2ClientConfiguration when the spring-security-oauth2-client module is present on the classpath
HttpSecurityConfiguration: configures various aspects of HTTP security and exposes the HttpSecurity bean

2. Using @EnableWebSecurity in Spring Boot applications

In a Spring Boot application, using the @EnableWebSecurity annotation is not mandatory because Spring Security auto configurations will import this annotation in the SecurityAutoConfiguration class, which imports the SpringBootWebSecurityConfiguration class that uses this annotation.

Additionally, if you dive deeper into the source code, you’ll see that this annotation is also a @EnableGlobalAuthentication, which indicates that the annotated class can be used to configure a global instance of AuthenticationManagerBuilder.

It also imports AuthenticationConfiguration which configures and exports key authentication beans, such as AuthenticationManagerBuilder and AuthenticationManager.

3. The @EnableWebSecurity annotation’s debug attribute

The @EnableWebSecurity annotation has only one attribute named debug. If enabled, it will print debugging information for Spring Security in the console. For example:

@Configuration
@EnableWebSecurity(debug = true)
public class AppSecurityConfig {

}

It will print the following notice in the console when the application starts:

********************************************************************
**********        Security debugging is enabled.       *************
**********    This may include sensitive information.  *************
**********      Do not use in a production system!     *************
********************************************************************

This means using @EnableWebSecurity(debug = true) should be for testing/development purpose. It should not be enabled in production. Also, enable debugging is often used to list spring security filters.

Conclusion

I hope you have found this post helpful in understanding the meaning and purpose of using the @EnableWebSecurity annotation in Spring. To conclude, you must use it in non-Spring Boot applications and it is optional in Spring Boot applications. That explains why the security of your Spring Boot application works regardless of you use this annotation or not.

Reference:

EnableWebSecurity Annotation Javadocs

Watch the video version of this article:

Other Spring Annotations:

Complete Spring framework Tutorials

About the Author:

Nam Ha Minh is certified Java programmer (SCJP and SCWCD). He began programming with Java back in the days of Java 1.4 and has been passionate about it ever since. You can connect with him on Facebook and watch his Java videos on YouTube.