Polish Getting Spring Security Reference

Fixes: gh-5921

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

@@ -1,9 +1,8 @@
 [[get-spring-security]]
 = Getting Spring Security
 
-You can get hold of Spring Security in several ways.
-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.
-
+This section discusses all you need to know about getting the Spring Security binaries.
+Please refer to <<community-source>> for how to obtain the source code.
 
 == Release Numbering
 
@@ -18,6 +17,81 @@ Typically these are done to provide improved security to match modern security p
 [[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:
 
 .pom.xml
@@ -29,18 +103,43 @@ A minimal Spring Security Maven set of dependencies typically looks like the fol
 	<dependency>
 		<groupId>org.springframework.security</groupId>
 		<artifactId>spring-security-web</artifactId>
-		<version>{spring-security-version}</version>
 	</dependency>
 	<dependency>
 		<groupId>org.springframework.security</groupId>
 		<artifactId>spring-security-config</artifactId>
-		<version>{spring-security-version}</version>
 	</dependency>
 </dependencies>
 ----
 
 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
 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>
 		<id>spring-snapshot</id>
 		<name>Spring Snapshot Repository</name>
-		<url>http://repo.spring.io/snapshot</url>
+		<url>https://repo.spring.io/snapshot</url>
 	</repository>
 </repositories>
 ----
@@ -70,58 +169,114 @@ If you are using a milestone or release candidate version, you will need to ensu
 	<repository>
 		<id>spring-milestone</id>
 		<name>Spring Milestone Repository</name>
-		<url>http://repo.spring.io/milestone</url>
+		<url>https://repo.spring.io/milestone</url>
 	</repository>
 </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.
+[[gradle]]
+== Gradle
 
-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:
+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.
 
-.pom.xml
-[source,xml]
+=== 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
+[source,groovy]
 [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>
+dependencies {
+	compile "org.springframework.boot:spring-boot-starter-security"
+}
 ----
 
-This will ensure that all the transitive dependencies of Spring Security use the Spring {spring-version} modules.
+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:
 
-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].
+.build.gradle
+[source,groovy]
+[subs="verbatim,attributes"]
+----
+ext['spring-security.version']='{spring-security-version}'
+----
 
-[[gradle]]
-== Gradle
-A minimal Spring Security Gradle set of dependencies typically looks like the following:
+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:{spring-security-version}'
-	compile 'org.springframework.security:spring-security-config:{spring-security-version}'
+	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>>.
 
+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
 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' }
 }
 ----
-
-[[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.