Rob Winch
parent
fe080cadbe
commit
cbb25f7b87
|
|
@ -1,9 +1,8 @@
|
||||||
[[get-spring-security]]
|
[[get-spring-security]]
|
||||||
= Getting Spring Security
|
= Getting Spring Security
|
||||||
|
|
||||||
You can get hold of Spring Security in several ways.
|
This section discusses all you need to know about getting the Spring Security binaries.
|
||||||
You can download a packaged distribution from the main http://spring.io/spring-security[Spring Security] page, download individual jars from the Maven Central repository (or a Spring Maven repository for snapshot and milestone releases) or, alternatively, you can build the project from source yourself.
|
Please refer to <<community-source>> for how to obtain the source code.
|
||||||
|
|
||||||
|
|
||||||
== Release Numbering
|
== Release Numbering
|
||||||
|
|
||||||
|
|
@ -18,6 +17,81 @@ Typically these are done to provide improved security to match modern security p
|
||||||
[[maven]]
|
[[maven]]
|
||||||
== Usage with Maven
|
== Usage with Maven
|
||||||
|
|
||||||
|
Like most open source projects, Spring Security deploys its dependencies as Maven artifacts.
|
||||||
|
The following sections provide details on how to consume Spring Security when using Maven.
|
||||||
|
|
||||||
|
=== Spring Boot with Maven
|
||||||
|
|
||||||
|
Spring Boot provides a spring-boot-starter-security starter which aggregates Spring Security related dependencies together.
|
||||||
|
The simplest and preferred method to leverage the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] using an IDE integration (http://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], 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, the starter can be added manually:
|
||||||
|
|
||||||
|
.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, there is no need to specify a version.
|
||||||
|
If you wish to override the Spring Security version, you may do so by providing a Maven property:
|
||||||
|
|
||||||
|
.pom.xml
|
||||||
|
[source,xml]
|
||||||
|
[subs="verbatim,attributes"]
|
||||||
|
----
|
||||||
|
<properties>
|
||||||
|
<!-- ... -->
|
||||||
|
<spring-security.version>{spring-security-version}</spring.security.version>
|
||||||
|
</dependencies>
|
||||||
|
----
|
||||||
|
|
||||||
|
Since Spring Security only makes breaking changes in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
|
||||||
|
However, at times it may be necessary to update the version of Spring Framework as well.
|
||||||
|
This can easily be done by adding a Maven property as well:
|
||||||
|
|
||||||
|
.pom.xml
|
||||||
|
[source,xml]
|
||||||
|
[subs="verbatim,attributes"]
|
||||||
|
----
|
||||||
|
<properties>
|
||||||
|
<!-- ... -->
|
||||||
|
<spring.version>{spring-version}</spring.version>
|
||||||
|
</dependencies>
|
||||||
|
----
|
||||||
|
|
||||||
|
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||||
|
|
||||||
|
=== Maven Without Spring Boot
|
||||||
|
|
||||||
|
When using Spring Security without Spring Boot, the preferred way is to leverage Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
|
||||||
|
|
||||||
|
.pom.xml
|
||||||
|
[source,xml]
|
||||||
|
[subs="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:
|
A minimal Spring Security Maven set of dependencies typically looks like the following:
|
||||||
|
|
||||||
.pom.xml
|
.pom.xml
|
||||||
|
|
@ -29,18 +103,43 @@ A minimal Spring Security Maven set of dependencies typically looks like the fol
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.springframework.security</groupId>
|
<groupId>org.springframework.security</groupId>
|
||||||
<artifactId>spring-security-web</artifactId>
|
<artifactId>spring-security-web</artifactId>
|
||||||
<version>{spring-security-version}</version>
|
|
||||||
</dependency>
|
</dependency>
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.springframework.security</groupId>
|
<groupId>org.springframework.security</groupId>
|
||||||
<artifactId>spring-security-config</artifactId>
|
<artifactId>spring-security-config</artifactId>
|
||||||
<version>{spring-security-version}</version>
|
|
||||||
</dependency>
|
</dependency>
|
||||||
</dependencies>
|
</dependencies>
|
||||||
----
|
----
|
||||||
|
|
||||||
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||||
|
|
||||||
|
Spring Security builds against Spring Framework {spring-version}, but should generally work with any newer version of Spring Framework 5.x
|
||||||
|
The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-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 `pom.xml` as shown below:
|
||||||
|
|
||||||
|
.pom.xml
|
||||||
|
[source,xml]
|
||||||
|
[subs="verbatim,attributes"]
|
||||||
|
----
|
||||||
|
<dependencyManagement>
|
||||||
|
<dependencies>
|
||||||
|
<!-- ... other dependency elements ... -->
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.springframework</groupId>
|
||||||
|
<artifactId>spring-framework-bom</artifactId>
|
||||||
|
<version>{spring-version}</version>
|
||||||
|
<type>pom</type>
|
||||||
|
<scope>import</scope>
|
||||||
|
</dependency>
|
||||||
|
</dependencies>
|
||||||
|
</dependencyManagement>
|
||||||
|
----
|
||||||
|
|
||||||
|
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-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 refer to http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
|
||||||
|
|
||||||
[[maven-repositories]]
|
[[maven-repositories]]
|
||||||
=== Maven Repositories
|
=== Maven Repositories
|
||||||
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
|
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
|
||||||
|
|
@ -55,7 +154,7 @@ If you are using a SNAPSHOT version, you will need to ensure you have the Spring
|
||||||
<repository>
|
<repository>
|
||||||
<id>spring-snapshot</id>
|
<id>spring-snapshot</id>
|
||||||
<name>Spring Snapshot Repository</name>
|
<name>Spring Snapshot Repository</name>
|
||||||
<url>http://repo.spring.io/snapshot</url>
|
<url>https://repo.spring.io/snapshot</url>
|
||||||
</repository>
|
</repository>
|
||||||
</repositories>
|
</repositories>
|
||||||
----
|
----
|
||||||
|
|
@ -70,58 +169,114 @@ If you are using a milestone or release candidate version, you will need to ensu
|
||||||
<repository>
|
<repository>
|
||||||
<id>spring-milestone</id>
|
<id>spring-milestone</id>
|
||||||
<name>Spring Milestone Repository</name>
|
<name>Spring Milestone Repository</name>
|
||||||
<url>http://repo.spring.io/milestone</url>
|
<url>https://repo.spring.io/milestone</url>
|
||||||
</repository>
|
</repository>
|
||||||
</repositories>
|
</repositories>
|
||||||
----
|
----
|
||||||
|
|
||||||
[[maven-bom]]
|
|
||||||
=== Spring Framework BOM
|
|
||||||
|
|
||||||
Spring Security builds against Spring Framework {spring-version}, but should work with 5
|
|
||||||
The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-version} which can cause strange classpath problems.
|
|
||||||
|
|
||||||
One (tedious) way to circumvent this issue would be to include all the Spring Framework modules in a http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Management[<dependencyManagement>] section of your pom.
|
|
||||||
An alternative approach is to include the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:
|
|
||||||
|
|
||||||
.pom.xml
|
|
||||||
[source,xml]
|
|
||||||
[subs="verbatim,attributes"]
|
|
||||||
----
|
|
||||||
<dependencyManagement>
|
|
||||||
<dependencies>
|
|
||||||
<dependency>
|
|
||||||
<groupId>org.springframework</groupId>
|
|
||||||
<artifactId>spring-framework-bom</artifactId>
|
|
||||||
<version>{spring-version}</version>
|
|
||||||
<type>pom</type>
|
|
||||||
<scope>import</scope>
|
|
||||||
</dependency>
|
|
||||||
</dependencies>
|
|
||||||
</dependencyManagement>
|
|
||||||
----
|
|
||||||
|
|
||||||
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-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 refer to http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
|
|
||||||
|
|
||||||
[[gradle]]
|
[[gradle]]
|
||||||
== Gradle
|
== Gradle
|
||||||
A minimal Spring Security Gradle set of dependencies typically looks like the following:
|
|
||||||
|
Like most open source projects, Spring Security deploys its dependencies as Maven artifacts which allows for for first class Gradle support.
|
||||||
|
The following sections provide details on how to consume Spring Security when using Gradle.
|
||||||
|
|
||||||
|
=== Spring Boot with Gradle
|
||||||
|
|
||||||
|
Spring Boot provides a spring-boot-starter-security starter which aggregates Spring Security related dependencies together.
|
||||||
|
The simplest and preferred method to leverage the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] using an IDE integration (http://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], 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, the starter can be added manually:
|
||||||
|
|
||||||
.build.gradle
|
.build.gradle
|
||||||
[source,groovy]
|
[source,groovy]
|
||||||
[subs="verbatim,attributes"]
|
[subs="verbatim,attributes"]
|
||||||
----
|
----
|
||||||
dependencies {
|
dependencies {
|
||||||
compile 'org.springframework.security:spring-security-web:{spring-security-version}'
|
compile "org.springframework.boot:spring-boot-starter-security"
|
||||||
compile 'org.springframework.security:spring-security-config:{spring-security-version}'
|
}
|
||||||
|
----
|
||||||
|
|
||||||
|
Since Spring Boot provides a Maven BOM to manage dependency versions, there is no need to specify a version.
|
||||||
|
If you wish to override the Spring Security version, you may do so by providing a Gradle property:
|
||||||
|
|
||||||
|
.build.gradle
|
||||||
|
[source,groovy]
|
||||||
|
[subs="verbatim,attributes"]
|
||||||
|
----
|
||||||
|
ext['spring-security.version']='{spring-security-version}'
|
||||||
|
----
|
||||||
|
|
||||||
|
Since Spring Security only makes breaking changes in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
|
||||||
|
However, at times it may be necessary to update the version of Spring Framework as well.
|
||||||
|
This can easily be done by adding a Gradle property as well:
|
||||||
|
|
||||||
|
.build.gradle
|
||||||
|
[source,groovy]
|
||||||
|
[subs="verbatim,attributes"]
|
||||||
|
----
|
||||||
|
ext['spring.version']='{spring-version}'
|
||||||
|
----
|
||||||
|
|
||||||
|
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||||
|
|
||||||
|
=== Gradle Without Spring Boot
|
||||||
|
|
||||||
|
When using Spring Security without Spring Boot, the preferred way is to leverage Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
|
||||||
|
This can be done 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 are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
|
||||||
|
|
||||||
|
Spring Security builds against Spring Framework {spring-version}, but should generally work with any newer version of Spring Framework 5.x
|
||||||
|
The problem that many users will have is that Spring Security's transitive dependencies resolve Spring Framework {spring-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 `pom.xml` as shown below:
|
||||||
|
This can be done 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-version}'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
----
|
||||||
|
|
||||||
|
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
|
||||||
|
|
||||||
[[gradle-repositories]]
|
[[gradle-repositories]]
|
||||||
=== Gradle Repositories
|
=== Gradle Repositories
|
||||||
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases.
|
All GA releases (i.e. versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases.
|
||||||
|
|
@ -153,27 +308,3 @@ repositories {
|
||||||
maven { url 'https://repo.spring.io/milestone' }
|
maven { url 'https://repo.spring.io/milestone' }
|
||||||
}
|
}
|
||||||
----
|
----
|
||||||
|
|
||||||
[[gradle-resolutionStrategy]]
|
|
||||||
=== Using Spring 4.0.x and Gradle
|
|
||||||
|
|
||||||
By default Gradle will use the newest version when resolving transitive versions.
|
|
||||||
This means that often times no additional work is necessary when running Spring Security {spring-security-version} with Spring Framework {spring-version}.
|
|
||||||
However, at times there can be issues that come up so it is best to mitigate this using http://www.gradle.org/docs/current/dsl/org.gradle.api.artifacts.ResolutionStrategy.html[Gradle's ResolutionStrategy] as shown below:
|
|
||||||
|
|
||||||
.build.gradle
|
|
||||||
[source,groovy]
|
|
||||||
[subs="verbatim,attributes"]
|
|
||||||
----
|
|
||||||
configurations.all {
|
|
||||||
resolutionStrategy.eachDependency { DependencyResolveDetails details ->
|
|
||||||
if (details.requested.group == 'org.springframework') {
|
|
||||||
details.useVersion '{spring-version}'
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
----
|
|
||||||
|
|
||||||
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
|
|
||||||
|
|
||||||
NOTE: This example uses Gradle 1.9, but may need modifications to work in future versions of Gradle since this is an incubating feature within Gradle.
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue