Skip to content

Commit 25b5f48

Browse files
jzheauxJay Bryantrwinch
committed
Rewrite Preface
Issue gh-2567 Co-authored-by: Jay Bryant <[email protected]> Co-authored-by: Rob Winch <[email protected]>
1 parent f832d08 commit 25b5f48

12 files changed

+509
-585
lines changed

‎docs/manual/src/docs/asciidoc/_includes/about/community.adoc

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
[[community]]
2+
= Spring Security Community
3+
4+
Welcome to the Spring Security Community!
5+
This section discusses how you can make the most of our vast community.
6+
7+
8+
[[community-help]]
9+
== Getting Help
10+
If you need help with Spring Security, we are here to help.
11+
The following are some of the best ways to get help:
12+
13+
* Read through this documentation.
14+
* Try one of our many <<samples,sample applications>>.
15+
* Ask a question on https://stackoverflow.com/questions/tagged/spring-security[https://stackoverflow.com] with the `spring-security` tag.
16+
* Report bugs and enhancement requests at https://github.com/spring-projects/spring-security/issues
17+
18+
[[community-becoming-involved]]
19+
== Becoming Involved
20+
We welcome your involvement in the Spring Security project.
21+
There are many ways to contribute, including answering questions on StackOverflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
22+
For more information, see our https://github.com/spring-projects/spring-security/blob/master/CONTRIBUTING.md[Contributing] documentation.
23+
24+
[[community-source]]
25+
== Source Code
26+
27+
You can find Spring Security's source code on GitHub at https://github.com/spring-projects/spring-security/
28+
29+
[[community-license]]
30+
== Apache 2 License
31+
32+
Spring Security is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].
33+
34+
== Social Media
35+
36+
You can follow https://twitter.com/SpringSecurity[@SpringSecurity] and the https://twitter.com/SpringSecurity/lists/team[Spring Security team] on Twitter to stay up to date with the latest news.
37+
You can also follow https://twitter.com/SpringCentral[@SpringCentral] to keep up to date with the entire Spring portfolio.

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

+344
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
[[getting]]
2+
= Getting Spring Security
3+
4+
This section discusses all you need to know about getting the Spring Security binaries.
5+
See <<community-source>> for how to obtain the source code.
6+
7+
== Release Numbering
8+
9+
Spring Security versions are formatted as MAJOR.MINOR.PATCH such that:
10+
11+
* MAJOR versions may contain breaking changes.
12+
Typically, these are done to provide improved security to match modern security practices.
13+
* MINOR versions contain enhancements but are considered passive updates
14+
* PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes that fix bugs.
15+
16+
17+
[[maven]]
18+
== Usage with Maven
19+
20+
As most open source projects, Spring Security deploys its dependencies as Maven artifacts.
21+
The topics in this section provide detail on how to consume Spring Security when using Maven.
22+
23+
[[getting-maven-boot]]
24+
=== Spring Boot with Maven
25+
26+
Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies together.
27+
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 (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.
28+
29+
Alternatively, you can manually add the starter, as the following example shows:
30+
31+
32+
.pom.xml
33+
====
34+
[source,xml]
35+
[subs="verbatim,attributes"]
36+
----
37+
<dependencies>
38+
<!-- ... other dependency elements ... -->
39+
<dependency>
40+
<groupId>org.springframework.boot</groupId>
41+
<artifactId>spring-boot-starter-security</artifactId>
42+
</dependency>
43+
</dependencies>
44+
----
45+
====
46+
47+
Since Spring Boot provides a Maven BOM to manage dependency versions, you do not need to specify a version.
48+
If you wish to override the Spring Security version, you may do so by providing a Maven property, as the following example shows:
49+
50+
.pom.xml
51+
====
52+
[source,xml]
53+
[subs="verbatim,attributes"]
54+
----
55+
<properties>
56+
<!-- ... -->
57+
<spring-security.version>{spring-security-version}</spring-security.version>
58+
</dependencies>
59+
----
60+
====
61+
62+
Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
63+
However, at times, you may need to update the version of Spring Framework as well.
64+
You can do so by adding a Maven property, as the following example shows:
65+
66+
.pom.xml
67+
====
68+
[source,xml]
69+
[subs="verbatim,attributes"]
70+
----
71+
<properties>
72+
<!-- ... -->
73+
<spring.version>{spring-version}</spring.version>
74+
</dependencies>
75+
----
76+
====
77+
78+
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
79+
80+
=== Maven Without Spring Boot
81+
82+
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. The following example shows how to do so:
83+
84+
.pom.xml
85+
====
86+
[source,xml]
87+
[subs="verbatim,attributes"]
88+
----
89+
<dependencyManagement>
90+
<dependencies>
91+
<!-- ... other dependency elements ... -->
92+
<dependency>
93+
<groupId>org.springframework.security</groupId>
94+
<artifactId>spring-security-bom</artifactId>
95+
<version>{spring-security-version}</version>
96+
<type>pom</type>
97+
<scope>import</scope>
98+
</dependency>
99+
</dependencies>
100+
</dependencyManagement>
101+
----
102+
====
103+
104+
A minimal Spring Security Maven set of dependencies typically looks like the following:
105+
106+
.pom.xml
107+
====
108+
[source,xml]
109+
[subs="verbatim,attributes"]
110+
----
111+
<dependencies>
112+
<!-- ... other dependency elements ... -->
113+
<dependency>
114+
<groupId>org.springframework.security</groupId>
115+
<artifactId>spring-security-web</artifactId>
116+
</dependency>
117+
<dependency>
118+
<groupId>org.springframework.security</groupId>
119+
<artifactId>spring-security-config</artifactId>
120+
</dependency>
121+
</dependencies>
122+
----
123+
====
124+
125+
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
126+
127+
Spring Security builds against Spring Framework {spring-version} but should generally work with any newer version of Spring Framework 5.x.
128+
Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-version}, which can cause strange classpath problems.
129+
The easiest way to resolve this is to use the `spring-framework-bom` within the `<dependencyManagement>` section of your `pom.xml` as the following example shows:
130+
131+
.pom.xml
132+
====
133+
[source,xml]
134+
[subs="verbatim,attributes"]
135+
----
136+
<dependencyManagement>
137+
<dependencies>
138+
<!-- ... other dependency elements ... -->
139+
<dependency>
140+
<groupId>org.springframework</groupId>
141+
<artifactId>spring-framework-bom</artifactId>
142+
<version>{spring-version}</version>
143+
<type>pom</type>
144+
<scope>import</scope>
145+
</dependency>
146+
</dependencies>
147+
</dependencyManagement>
148+
----
149+
====
150+
151+
The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
152+
153+
NOTE: This approach uses Maven's "`bill of materials`" (BOM) concept and is only available in Maven 2.0.9+.
154+
For additional details about how dependencies are resolved, see http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
155+
156+
[[maven-repositories]]
157+
=== Maven Repositories
158+
All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
159+
160+
If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined, as the following example shows:
161+
162+
.pom.xml
163+
====
164+
[source,xml]
165+
----
166+
<repositories>
167+
<!-- ... possibly other repository elements ... -->
168+
<repository>
169+
<id>spring-snapshot</id>
170+
<name>Spring Snapshot Repository</name>
171+
<url>https://repo.spring.io/snapshot</url>
172+
</repository>
173+
</repositories>
174+
----
175+
====
176+
177+
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:
178+
179+
.pom.xml
180+
====
181+
[source,xml]
182+
----
183+
<repositories>
184+
<!-- ... possibly other repository elements ... -->
185+
<repository>
186+
<id>spring-milestone</id>
187+
<name>Spring Milestone Repository</name>
188+
<url>https://repo.spring.io/milestone</url>
189+
</repository>
190+
</repositories>
191+
----
192+
====
193+
194+
[[getting-gradle]]
195+
== Gradle
196+
197+
As most open source projects, Spring Security deploys its dependencies as Maven artifacts, which allows for for first-class Gradle support.
198+
The following topics provide detail on how to consume Spring Security when using Gradle.
199+
200+
[[getting-gradle-boot]]
201+
=== Spring Boot with Gradle
202+
203+
Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies together.
204+
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 (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.
205+
206+
Alternatively, you can manually add the starter, as the following example shows:
207+
208+
.build.gradle
209+
====
210+
[source,groovy]
211+
[subs="verbatim,attributes"]
212+
----
213+
dependencies {
214+
compile "org.springframework.boot:spring-boot-starter-security"
215+
}
216+
----
217+
====
218+
219+
Since Spring Boot provides a Maven BOM to manage dependency versions, you need not specify a version.
220+
If you wish to override the Spring Security version, you may do so by providing a Gradle property, as the following example shows:
221+
222+
.build.gradle
223+
====
224+
[source,groovy]
225+
[subs="verbatim,attributes"]
226+
----
227+
ext['spring-security.version']='{spring-security-version}'
228+
----
229+
====
230+
231+
Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
232+
However, at times, you may need to update the version of Spring Framework as well.
233+
You can do so by adding a Gradle property, as the following example shows:
234+
235+
.build.gradle
236+
====
237+
[source,groovy]
238+
[subs="verbatim,attributes"]
239+
----
240+
ext['spring.version']='{spring-version}'
241+
----
242+
====
243+
244+
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
245+
246+
=== Gradle Without Spring Boot
247+
248+
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.
249+
You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
250+
251+
.build.gradle
252+
====
253+
[source,groovy]
254+
[subs="verbatim,attributes"]
255+
----
256+
plugins {
257+
id "io.spring.dependency-management" version "1.0.6.RELEASE"
258+
}
259+
260+
dependencyManagement {
261+
imports {
262+
mavenBom 'org.springframework.security:spring-security-bom:{spring-security-version}'
263+
}
264+
}
265+
----
266+
====
267+
268+
A minimal Spring Security Maven set of dependencies typically looks like the following:
269+
270+
.build.gradle
271+
====
272+
[source,groovy]
273+
[subs="verbatim,attributes"]
274+
----
275+
dependencies {
276+
compile "org.springframework.security:spring-security-web"
277+
compile "org.springframework.security:spring-security-config"
278+
}
279+
----
280+
====
281+
282+
If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
283+
284+
Spring Security builds against Spring Framework {spring-version} but should generally work with any newer version of Spring Framework 5.x. {JB}
285+
Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-version}, which can cause strange classpath problems.
286+
The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml`.
287+
You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
288+
289+
.build.gradle
290+
====
291+
[source,groovy]
292+
[subs="verbatim,attributes"]
293+
----
294+
plugins {
295+
id "io.spring.dependency-management" version "1.0.6.RELEASE"
296+
}
297+
298+
dependencyManagement {
299+
imports {
300+
mavenBom 'org.springframework:spring-framework-bom:{spring-version}'
301+
}
302+
}
303+
----
304+
====
305+
306+
The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
307+
308+
[[gradle-repositories]]
309+
=== Gradle Repositories
310+
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:
311+
312+
.build.gradle
313+
====
314+
[source,groovy]
315+
----
316+
repositories {
317+
mavenCentral()
318+
}
319+
----
320+
====
321+
322+
If you use a SNAPSHOT version, you need to ensure you have the Spring Snapshot repository defined, as the following example shows:
323+
324+
.build.gradle
325+
====
326+
[source,groovy]
327+
----
328+
repositories {
329+
maven { url 'https://repo.spring.io/snapshot' }
330+
}
331+
----
332+
====
333+
334+
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:
335+
336+
.build.gradle
337+
====
338+
[source,groovy]
339+
----
340+
repositories {
341+
maven { url 'https://repo.spring.io/milestone' }
342+
}
343+
----
344+
====

‎docs/manual/src/docs/asciidoc/_includes/preface/index.adoc renamed to ‎docs/manual/src/docs/asciidoc/_includes/about/index.adoc

+4-2
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,14 @@
22

33
This section discusses the logistics of Spring Security.
44

5-
include::community.adoc[]
5+
include::prerequisites.adoc[leveloffset=+1]
6+
7+
include::community.adoc[leveloffset=+1]
68

79
include::whats-new.adoc[]
810

911
include::getting-spring-security.adoc[leveloffset=+1]
1012

1113
include::modules.adoc[leveloffset=+1]
1214

13-
include::samples.adoc[]
15+
include::samples.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)