Introduction to Spring Security

Prerequisites

Spring Security requires the Java 8 runtime or higher.

Because Spring Security aims to be standalone, you don't need to place any special configuration files in the Java runtime. In particular, you don't need to configure a special Java Authentication and Authorization Service (JAAS) policy file or place Spring Security in common classpath locations.

Likewise, if you use an EJB Container or Servlet Container, you don't need to place special configuration files anywhere or include Spring Security in the server class loader. All necessary files are contained within your application.

This design allows for maximum deployment flexibility because you can copy the target artifact (be it a JAR, WAR, or EAR) from one system to another and have it work immediately.

This section describes everything you need to know about obtaining Spring Security binaries. To obtain the source code, see "Source Code".

Issue numbering

Spring Security versions are classified by MAJOR.MINOR.PATCH as follows:

• MAJOR versions may contain breaking changes. Typically, this is done to ensure increased security in accordance with modern security methods.

• MINOR versions contain improvements, but are considered passive updates

• The PATCH level must be perfectly compatible with both subsequent and previous versions, except for changes that correct errors.

Use with Maven

Like most open source projects, Spring Security deploys its dependencies as Maven artifacts. The articles in this section detail how to use Spring Security with Maven.

Spring Boot using Maven

Spring Boot contains a starter spring-boot-starter-security that bundles Spring Security-related dependencies together. The easiest and preferred way to use the starter is to use Spring Initializr via integration with IDE (Eclipse, IntelliJ, NetBeans) or via start.spring.io.

You can also manually add a starter, as shown in the following example:

<dependencies>
  <!-- ... other dependency elements ... -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
  </dependency>
</dependencies>

Because Spring Boot uses the Maven BOM to version dependencies, you do not need to specify a version. If you need to override the Spring Security version, you can do so by setting the Maven property, as shown in the following example:

<properties>
  <!-- ... -->
  <spring-security.version>5.7.4</spring-security.version>
</properties>

Since Spring Security changes only in major releases, you can safely use a newer version of Spring Security with Spring Boot. However, sometimes you may need to update the Spring Framework version as well. You can do this by adding a Maven property, as shown in the following example:

<properties>
  <!-- ... -->
  <spring.version>5.3.23</spring.version>
</properties>

If you use additional features (such as LDAP, OpenID and others), you will also need to add the appropriate modules and project dependencies.

Maven without using Spring Boot

If you are working with Spring Security without Spring Boot, your best bet is to use the BOM specification for Spring Security, which will ensure that the Spring Security version is used consistently throughout the project. The following example shows how to do this:

<dependencyManagement>
  <dependencies>
    <!-- ... other dependency elements ... -->
    <dependency>
      <groupId>org.springframework.security</groupId>
      <artifactId>spring-security-bom</artifactId>
      <version>{spring-security-version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

The minimum set of Spring Security dependencies for Maven usually looks like this:

<dependencies>
  <!-- ... other dependency elements ... -->
  <dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-config</artifactId>
  </dependency>
</dependencies>

Spring Security builds on Spring Framework 5.3.23, but should generally work with any newer version of Spring Framework 5.x. Many users will likely find that Spring Security's transitive dependencies are resolved by Spring Framework 5.3.23, which can cause strange classpath issues. The easiest way to solve this problem is to use spring-framework-bom in the <dependencyManagement> section of your pom.xml as shown in the following example :

<dependencyManagement>
  <dependencies>
    <!-- ... other dependency elements ... -->
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-framework-bom</artifactId>
      <version>5.3.23</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

In the previous example, all Spring Security transitive dependencies are guaranteed to use Spring 5.3.23 modules.

Maven Repositories

All public releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so there is no need to declare additional Maven repositories in the pom file.

If you are using the SNAPSHOT version, you must ensure that a repository for Spring snapshot versions has been defined, as shown in the following example:

<repositories>
  <!-- ... other possible repository elements ... -->
  <repository>
    <id>spring-snapshot</id>
    <name>Spring Snapshot Repository</name>
    <url>https://repo.spring.io/snapshot</url>
  </repository>
</repositories>

If you are using a stable or pre-release version, you need to ensure that a repository for the stable versions of Spring has been defined, as shown in the following example:

<repositories>
  <!-- ... other possible repository elements ... -->
  <repository>
    <id>spring-milestone</id>
    <name>Spring Milestone Repository</name>
    <url>https://repo.spring.io/milestone</url>
  </repository>
</repositories>