Skip to content

Commit cbb25f7

Browse files
rwinchrwinch
committed
Polish Getting Spring Security Reference
Fixes: gh-5921
1 parent fe080ca commit cbb25f7

File tree

1 file changed

+189
-58
lines changed

1 file changed

+189
-58
lines changed

‎docs/manual/src/docs/asciidoc/_includes/preface/getting-spring-security.adoc

Lines changed: 189 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
[[get-spring-security]]
22
= Getting Spring Security
33

4-
You can get hold of Spring Security in several ways.
5-
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.
6-
4+
This section discusses all you need to know about getting the Spring Security binaries.
5+
Please refer to <<community-source>> for how to obtain the source code.
76

87
== Release Numbering
98

@@ -18,6 +17,81 @@ Typically these are done to provide improved security to match modern security p
1817
[[maven]]
1918
== Usage with Maven
2019

20+
Like most open source projects, Spring Security deploys its dependencies as Maven artifacts.
21+
The following sections provide details on how to consume Spring Security when using Maven.
22+
23+
=== Spring Boot with Maven
24+
25+
Spring Boot provides a spring-boot-starter-security starter which aggregates Spring Security related dependencies together.
26+
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.
27+
28+
Alternatively, the starter can be added manually:
29+
30+
.pom.xml
31+
[source,xml]
32+
[subs="verbatim,attributes"]
33+
----
34+
<dependencies>
35+
<!-- ... other dependency elements ... -->
36+
<dependency>
37+
<groupId>org.springframework.boot</groupId>
38+
<artifactId>spring-boot-starter-security</artifactId>
39+
</dependency>
40+
</dependencies>
41+
----
42+
43+
Since Spring Boot provides a Maven BOM to manage dependency versions, there is no need to specify a version.
44+
If you wish to override the Spring Security version, you may do so by providing a Maven property:
45+
46+
.pom.xml
47+
[source,xml]
48+
[subs="verbatim,attributes"]
49+
----
50+
<properties>
51+
<!-- ... -->
52+
<spring-security.version>{spring-security-version}</spring.security.version>
53+
</dependencies>
54+
----
55+
56+
Since Spring Security only makes breaking changes in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
57+
However, at times it may be necessary to update the version of Spring Framework as well.
58+
This can easily be done by adding a Maven property as well:
59+
60+
.pom.xml
61+
[source,xml]
62+
[subs="verbatim,attributes"]
63+
----
64+
<properties>
65+
<!-- ... -->
66+
<spring.version>{spring-version}</spring.version>
67+
</dependencies>
68+
----
69+
70+
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
71+
72+
=== Maven Without Spring Boot
73+
74+
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.
75+
76+
.pom.xml
77+
[source,xml]
78+
[subs="verbatim,attributes"]
79+
----
80+
<dependencyManagement>
81+
<dependencies>
82+
<!-- ... other dependency elements ... -->
83+
<dependency>
84+
<groupId>org.springframework.security</groupId>
85+
<artifactId>spring-security-bom</artifactId>
86+
<version>{spring-security-version}</version>
87+
<type>pom</type>
88+
<scope>import</scope>
89+
</dependency>
90+
</dependencies>
91+
</dependencyManagement>
92+
----
93+
94+
2195
A minimal Spring Security Maven set of dependencies typically looks like the following:
2296

2397
.pom.xml
@@ -29,18 +103,43 @@ A minimal Spring Security Maven set of dependencies typically looks like the fol
29103
<dependency>
30104
<groupId>org.springframework.security</groupId>
31105
<artifactId>spring-security-web</artifactId>
32-
<version>{spring-security-version}</version>
33106
</dependency>
34107
<dependency>
35108
<groupId>org.springframework.security</groupId>
36109
<artifactId>spring-security-config</artifactId>
37-
<version>{spring-security-version}</version>
38110
</dependency>
39111
</dependencies>
40112
----
41113

42114
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
43115

116+
Spring Security builds against Spring Framework {spring-version}, but should generally work with any newer version of Spring Framework 5.x
117+
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.
118+
The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:
119+
120+
.pom.xml
121+
[source,xml]
122+
[subs="verbatim,attributes"]
123+
----
124+
<dependencyManagement>
125+
<dependencies>
126+
<!-- ... other dependency elements ... -->
127+
<dependency>
128+
<groupId>org.springframework</groupId>
129+
<artifactId>spring-framework-bom</artifactId>
130+
<version>{spring-version}</version>
131+
<type>pom</type>
132+
<scope>import</scope>
133+
</dependency>
134+
</dependencies>
135+
</dependencyManagement>
136+
----
137+
138+
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
139+
140+
NOTE: This approach uses Maven's "bill of materials" (BOM) concept and is only available in Maven 2.0.9+.
141+
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].
142+
44143
[[maven-repositories]]
45144
=== Maven Repositories
46145
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
55154
<repository>
56155
<id>spring-snapshot</id>
57156
<name>Spring Snapshot Repository</name>
58-
<url>http://repo.spring.io/snapshot</url>
157+
<url>https://repo.spring.io/snapshot</url>
59158
</repository>
60159
</repositories>
61160
----
@@ -70,58 +169,114 @@ If you are using a milestone or release candidate version, you will need to ensu
70169
<repository>
71170
<id>spring-milestone</id>
72171
<name>Spring Milestone Repository</name>
73-
<url>http://repo.spring.io/milestone</url>
172+
<url>https://repo.spring.io/milestone</url>
74173
</repository>
75174
</repositories>
76175
----
77176

78-
[[maven-bom]]
79-
=== Spring Framework BOM
80177

81-
Spring Security builds against Spring Framework {spring-version}, but should work with 5
82-
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.
178+
[[gradle]]
179+
== Gradle
83180

84-
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.
85-
An alternative approach is to include the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:
181+
Like most open source projects, Spring Security deploys its dependencies as Maven artifacts which allows for for first class Gradle support.
182+
The following sections provide details on how to consume Spring Security when using Gradle.
86183

87-
.pom.xml
88-
[source,xml]
184+
=== Spring Boot with Gradle
185+
186+
Spring Boot provides a spring-boot-starter-security starter which aggregates Spring Security related dependencies together.
187+
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.
188+
189+
Alternatively, the starter can be added manually:
190+
191+
.build.gradle
192+
[source,groovy]
89193
[subs="verbatim,attributes"]
90194
----
91-
<dependencyManagement>
92-
<dependencies>
93-
<dependency>
94-
<groupId>org.springframework</groupId>
95-
<artifactId>spring-framework-bom</artifactId>
96-
<version>{spring-version}</version>
97-
<type>pom</type>
98-
<scope>import</scope>
99-
</dependency>
100-
</dependencies>
101-
</dependencyManagement>
195+
dependencies {
196+
compile "org.springframework.boot:spring-boot-starter-security"
197+
}
102198
----
103199

104-
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
200+
Since Spring Boot provides a Maven BOM to manage dependency versions, there is no need to specify a version.
201+
If you wish to override the Spring Security version, you may do so by providing a Gradle property:
105202

106-
NOTE: This approach uses Maven's "bill of materials" (BOM) concept and is only available in Maven 2.0.9+.
107-
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].
203+
.build.gradle
204+
[source,groovy]
205+
[subs="verbatim,attributes"]
206+
----
207+
ext['spring-security.version']='{spring-security-version}'
208+
----
108209

109-
[[gradle]]
110-
== Gradle
111-
A minimal Spring Security Gradle set of dependencies typically looks like the following:
210+
Since Spring Security only makes breaking changes in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
211+
However, at times it may be necessary to update the version of Spring Framework as well.
212+
This can easily be done by adding a Gradle property as well:
213+
214+
.build.gradle
215+
[source,groovy]
216+
[subs="verbatim,attributes"]
217+
----
218+
ext['spring.version']='{spring-version}'
219+
----
220+
221+
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
222+
223+
=== Gradle Without Spring Boot
224+
225+
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.
226+
This can be done by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin].
227+
228+
.build.gradle
229+
[source,groovy]
230+
[subs="verbatim,attributes"]
231+
----
232+
plugins {
233+
id "io.spring.dependency-management" version "1.0.6.RELEASE"
234+
}
235+
236+
dependencyManagement {
237+
imports {
238+
mavenBom 'org.springframework.security:spring-security-bom:{spring-security-version}'
239+
}
240+
}
241+
----
242+
243+
244+
A minimal Spring Security Maven set of dependencies typically looks like the following:
112245

113246
.build.gradle
114247
[source,groovy]
115248
[subs="verbatim,attributes"]
116249
----
117250
dependencies {
118-
compile 'org.springframework.security:spring-security-web:{spring-security-version}'
119-
compile 'org.springframework.security:spring-security-config:{spring-security-version}'
251+
compile "org.springframework.security:spring-security-web"
252+
compile "org.springframework.security:spring-security-config"
120253
}
121254
----
122255

123256
If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<modules>>.
124257

258+
Spring Security builds against Spring Framework {spring-version}, but should generally work with any newer version of Spring Framework 5.x
259+
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.
260+
The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml` as shown below:
261+
This can be done by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin].
262+
263+
.build.gradle
264+
[source,groovy]
265+
[subs="verbatim,attributes"]
266+
----
267+
plugins {
268+
id "io.spring.dependency-management" version "1.0.6.RELEASE"
269+
}
270+
271+
dependencyManagement {
272+
imports {
273+
mavenBom 'org.springframework:spring-framework-bom:{spring-version}'
274+
}
275+
}
276+
----
277+
278+
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
279+
125280
[[gradle-repositories]]
126281
=== Gradle Repositories
127282
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 {
153308
maven { url 'https://repo.spring.io/milestone' }
154309
}
155310
----
156-
157-
[[gradle-resolutionStrategy]]
158-
=== Using Spring 4.0.x and Gradle
159-
160-
By default Gradle will use the newest version when resolving transitive versions.
161-
This means that often times no additional work is necessary when running Spring Security {spring-security-version} with Spring Framework {spring-version}.
162-
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:
163-
164-
.build.gradle
165-
[source,groovy]
166-
[subs="verbatim,attributes"]
167-
----
168-
configurations.all {
169-
resolutionStrategy.eachDependency { DependencyResolveDetails details ->
170-
if (details.requested.group == 'org.springframework') {
171-
details.useVersion '{spring-version}'
172-
}
173-
}
174-
}
175-
----
176-
177-
This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
178-
179-
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.

0 commit comments

Comments
 (0)