You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
307 lines
11 KiB
307 lines
11 KiB
[[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 { |
|
compile "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 { |
|
compile "org.springframework.security:spring-security-web" |
|
compile "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' } |
|
} |
|
----
|
|
|