From cbb25f7b873d8280fb90d60925ed7cee9e22aa94 Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Wed, 3 Oct 2018 14:48:31 -0400 Subject: [PATCH] Polish Getting Spring Security Reference Fixes: gh-5921 --- .../preface/getting-spring-security.adoc | 259 +++++++++++++----- 1 file changed, 195 insertions(+), 64 deletions(-) diff --git a/docs/manual/src/docs/asciidoc/_includes/preface/getting-spring-security.adoc b/docs/manual/src/docs/asciidoc/_includes/preface/getting-spring-security.adoc index 3dbdc62b06..0a483c3073 100644 --- a/docs/manual/src/docs/asciidoc/_includes/preface/getting-spring-security.adoc +++ b/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 <> 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"] +---- + + + + org.springframework.boot + spring-boot-starter-security + + +---- + +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"] +---- + + + {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 Maven property as well: + +.pom.xml +[source,xml] +[subs="verbatim,attributes"] +---- + + + {spring-version} + +---- + +If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <>. + +=== 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"] +---- + + + + + org.springframework.security + spring-security-bom + {spring-security-version} + pom + import + + + +---- + + 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 org.springframework.security spring-security-web - {spring-security-version} org.springframework.security spring-security-config - {spring-security-version} ---- If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <>. +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 `` section of your `pom.xml` as shown below: + +.pom.xml +[source,xml] +[subs="verbatim,attributes"] +---- + + + + + org.springframework + spring-framework-bom + {spring-version} + pom + import + + + +---- + +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 spring-snapshot Spring Snapshot Repository - http://repo.spring.io/snapshot + https://repo.spring.io/snapshot ---- @@ -70,58 +169,114 @@ If you are using a milestone or release candidate version, you will need to ensu spring-milestone Spring Milestone Repository - http://repo.spring.io/milestone + https://repo.spring.io/milestone ---- -[[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[] section of your pom. -An alternative approach is to include the `spring-framework-bom` within your `` section of your `pom.xml` as shown below: - -.pom.xml -[source,xml] -[subs="verbatim,attributes"] ----- - - - - org.springframework - spring-framework-bom - {spring-version} - pom - import - - - ----- - -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 -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 [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.boot:spring-boot-starter-security" +} +---- + +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 <>. + +=== 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 <>. +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 `` 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.