mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-31 06:38:42 +00:00
308 lines
11 KiB
Plaintext
308 lines
11 KiB
Plaintext
[[getting]]
|
|
= Getting Spring Security
|
|
|
|
This section describes how to get the Spring Security binaries.
|
|
See xref:community.adoc#community-source[Source Code] for how to obtain the source code.
|
|
|
|
== Release Numbering
|
|
|
|
Spring Security versions are formatted as MAJOR.MINOR.PATCH such that:
|
|
|
|
* MAJOR versions may contain breaking changes.
|
|
Typically, these are done to provide improved security to match modern security practices.
|
|
* MINOR versions contain enhancements but are considered passive updates.
|
|
* PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes that fix bugs.
|
|
|
|
|
|
[[maven]]
|
|
== Usage with Maven
|
|
|
|
As most open source projects, Spring Security deploys its dependencies as Maven artifacts.
|
|
The topics in this section describe how to consume Spring Security when using Maven.
|
|
|
|
[[getting-maven-boot]]
|
|
=== Spring Boot with Maven
|
|
|
|
Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies.
|
|
The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration in (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse] or https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
|
|
Alternatively, you can manually add the starter, as the following example shows:
|
|
|
|
|
|
.pom.xml
|
|
[source,xml,subs="verbatim,attributes"]
|
|
----
|
|
<dependencies>
|
|
<!-- ... other dependency elements ... -->
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-security</artifactId>
|
|
</dependency>
|
|
</dependencies>
|
|
----
|
|
|
|
Since Spring Boot provides a Maven BOM to manage dependency versions, you do not need to specify a version.
|
|
If you wish to override the Spring Security version, you can do so by providing a Maven property:
|
|
|
|
.pom.xml
|
|
[source,xml,subs="verbatim,attributes"]
|
|
----
|
|
<properties>
|
|
<!-- ... -->
|
|
<spring-security.version>{spring-security-version}</spring-security.version>
|
|
</properties>
|
|
----
|
|
|
|
Since Spring Security makes breaking changes only in major releases, you can safely use a newer version of Spring Security with Spring Boot.
|
|
However, at times, you may need to update the version of Spring Framework as well.
|
|
You can do so by adding a Maven property:
|
|
|
|
.pom.xml
|
|
[source,xml,subs="verbatim,attributes"]
|
|
----
|
|
<properties>
|
|
<!-- ... -->
|
|
<spring.version>{spring-core-version}</spring.version>
|
|
</properties>
|
|
----
|
|
|
|
If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
|
|
|
|
[[getting-maven-no-boot]]
|
|
=== Maven Without Spring Boot
|
|
|
|
When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure that a consistent version of Spring Security is used throughout the entire project. The following example shows how to do so:
|
|
|
|
.pom.xml
|
|
[source,xml,ubs="verbatim,attributes"]
|
|
----
|
|
<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>
|
|
----
|
|
|
|
A minimal Spring Security Maven set of dependencies typically looks like the following example:
|
|
|
|
.pom.xml
|
|
[source,xml,subs="verbatim,attributes"]
|
|
----
|
|
<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>
|
|
----
|
|
|
|
If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
|
|
|
|
Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x.
|
|
Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems.
|
|
The easiest way to resolve this is to use the `spring-framework-bom` within the `<dependencyManagement>` section of your `pom.xml`:
|
|
|
|
.pom.xml
|
|
[source,xml,subs="verbatim,attributes"]
|
|
----
|
|
<dependencyManagement>
|
|
<dependencies>
|
|
<!-- ... other dependency elements ... -->
|
|
<dependency>
|
|
<groupId>org.springframework</groupId>
|
|
<artifactId>spring-framework-bom</artifactId>
|
|
<version>{spring-core-version}</version>
|
|
<type>pom</type>
|
|
<scope>import</scope>
|
|
</dependency>
|
|
</dependencies>
|
|
</dependencyManagement>
|
|
----
|
|
|
|
The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-core-version} modules.
|
|
|
|
[NOTE]
|
|
====
|
|
This approach uses Maven's "`bill of materials`" (BOM) concept and is only available in Maven 2.0.9+.
|
|
For additional details about how dependencies are resolved, see https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
|
|
====
|
|
|
|
[[maven-repositories]]
|
|
=== Maven Repositories
|
|
All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so you need not declare additional Maven repositories in your pom.
|
|
|
|
If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined:
|
|
|
|
.pom.xml
|
|
[source,xml]
|
|
----
|
|
<repositories>
|
|
<!-- ... possibly other repository elements ... -->
|
|
<repository>
|
|
<id>spring-snapshot</id>
|
|
<name>Spring Snapshot Repository</name>
|
|
<url>https://repo.spring.io/snapshot</url>
|
|
</repository>
|
|
</repositories>
|
|
----
|
|
|
|
If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined, as the following example shows:
|
|
|
|
.pom.xml
|
|
[source,xml]
|
|
----
|
|
<repositories>
|
|
<!-- ... possibly other repository elements ... -->
|
|
<repository>
|
|
<id>spring-milestone</id>
|
|
<name>Spring Milestone Repository</name>
|
|
<url>https://repo.spring.io/milestone</url>
|
|
</repository>
|
|
</repositories>
|
|
----
|
|
|
|
[[getting-gradle]]
|
|
== Gradle
|
|
|
|
As most open source projects, Spring Security deploys its dependencies as Maven artifacts, which allows for first-class Gradle support.
|
|
The following topics describe how to consume Spring Security when using Gradle.
|
|
|
|
[[getting-gradle-boot]]
|
|
=== Spring Boot with Gradle
|
|
|
|
Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies.
|
|
The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration in (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse] or https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
|
|
|
|
Alternatively, you can manually add the starter:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
[subs="verbatim,attributes"]
|
|
----
|
|
dependencies {
|
|
implementation "org.springframework.boot:spring-boot-starter-security"
|
|
}
|
|
----
|
|
|
|
Since Spring Boot provides a Maven BOM to manage dependency versions, you need not specify a version.
|
|
If you wish to override the Spring Security version, you can do so by providing a Gradle property:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
[subs="verbatim,attributes"]
|
|
----
|
|
ext['spring-security.version']='{spring-security-version}'
|
|
----
|
|
|
|
Since Spring Security makes breaking changes only in major releases, you can safely use a newer version of Spring Security with Spring Boot.
|
|
However, at times, you may need to update the version of Spring Framework as well.
|
|
You can do so by adding a Gradle property:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
[subs="verbatim,attributes"]
|
|
----
|
|
ext['spring.version']='{spring-core-version}'
|
|
----
|
|
|
|
If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
|
|
|
|
=== Gradle Without Spring Boot
|
|
|
|
When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
|
|
You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin]:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
[subs="verbatim,attributes"]
|
|
----
|
|
plugins {
|
|
id "io.spring.dependency-management" version "1.0.6.RELEASE"
|
|
}
|
|
|
|
dependencyManagement {
|
|
imports {
|
|
mavenBom 'org.springframework.security:spring-security-bom:{spring-security-version}'
|
|
}
|
|
}
|
|
----
|
|
|
|
A minimal Spring Security Maven set of dependencies typically looks like the following:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
[subs="verbatim,attributes"]
|
|
----
|
|
dependencies {
|
|
implementation "org.springframework.security:spring-security-web"
|
|
implementation "org.springframework.security:spring-security-config"
|
|
}
|
|
----
|
|
|
|
If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies].
|
|
|
|
Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x.
|
|
Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems.
|
|
The easiest way to resolve this is to use the `spring-framework-bom` within your `dependencyManagement` section of your `build.gradle`.
|
|
You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin]:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
[subs="verbatim,attributes"]
|
|
----
|
|
plugins {
|
|
id "io.spring.dependency-management" version "1.0.6.RELEASE"
|
|
}
|
|
|
|
dependencyManagement {
|
|
imports {
|
|
mavenBom 'org.springframework:spring-framework-bom:{spring-core-version}'
|
|
}
|
|
}
|
|
----
|
|
|
|
The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-core-version} modules.
|
|
|
|
[[gradle-repositories]]
|
|
=== Gradle Repositories
|
|
All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so using the `mavenCentral()` repository is sufficient for GA releases. The following example shows how to do so:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
----
|
|
repositories {
|
|
mavenCentral()
|
|
}
|
|
----
|
|
|
|
If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
----
|
|
repositories {
|
|
maven { url 'https://repo.spring.io/snapshot' }
|
|
}
|
|
----
|
|
|
|
If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined:
|
|
|
|
.build.gradle
|
|
[source,groovy]
|
|
----
|
|
repositories {
|
|
maven { url 'https://repo.spring.io/milestone' }
|
|
}
|
|
----
|