From 4eaa8d23393b166f2f506f2e7e6d89e53588c96e Mon Sep 17 00:00:00 2001 From: Harpreet Singh Date: Mon, 9 Dec 2024 00:43:36 +0530 Subject: [PATCH 1/3] Use Tabs for Maven and Gradle Snippets Closes gh-16228 --- .../ROOT/pages/getting-spring-security.adoc | 294 ++++++++++-------- 1 file changed, 156 insertions(+), 138 deletions(-) diff --git a/docs/modules/ROOT/pages/getting-spring-security.adoc b/docs/modules/ROOT/pages/getting-spring-security.adoc index d391d871db0..22766a41423 100644 --- a/docs/modules/ROOT/pages/getting-spring-security.adoc +++ b/docs/modules/ROOT/pages/getting-spring-security.adoc @@ -1,4 +1,5 @@ [[getting]] +[[getting-gradle]] = Getting Spring Security This section describes how to get the Spring Security binaries. @@ -15,19 +16,22 @@ Typically, these are done to provide improved security to match modern security [[maven]] -== Usage with Maven +== Usage -As most open source projects, Spring Security deploys its dependencies as Maven artifacts. -The topics in this section describe how to consume Spring Security when using Maven. +As most open source projects, Spring Security deploys its dependencies as Maven artifacts, which makes them compatible with both Maven and Gradle. The following sections demonstrate how to integrate Spring Security with these build tools, with examples for Spring Boot and standalone usage. [[getting-maven-boot]] -=== Spring Boot with Maven +[[getting-gradle-boot]] +=== Spring Boot Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies. The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/html/[Spring Initializr] by using an IDE integration in (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse] or 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, you can manually add the starter, as the following example shows: - +[tabs] +====== +Maven:: ++ .pom.xml [source,xml,subs="verbatim,attributes"] ---- @@ -40,9 +44,25 @@ Alternatively, you can manually add the starter, as the following example shows: ---- +Gradle:: ++ +.build.gradle +[source,groovy] +[subs="verbatim,attributes"] +---- +dependencies { + implementation "org.springframework.boot:spring-boot-starter-security" +} +---- +====== + Since Spring Boot provides a Maven BOM to manage dependency versions, you do not need to specify a version. -If you wish to override the Spring Security version, you can do so by providing a Maven property: +If you wish to override the Spring Security version, you can do so with a build property as shown below: +[tabs] +====== +Maven:: ++ .pom.xml [source,xml,subs="verbatim,attributes"] ---- @@ -52,10 +72,24 @@ If you wish to override the Spring Security version, you can do so by providing ---- +Gradle:: ++ +.build.gradle +[source,groovy] +[subs="verbatim,attributes"] +---- +ext['spring-security.version']='{spring-security-version}' +---- +====== + Since Spring Security makes breaking changes only in major releases, you can safely use a newer version of Spring Security with Spring Boot. However, at times, you may need to update the version of Spring Framework as well. -You can do so by adding a Maven property: +You can do so by adding a build property like so: +[tabs] +====== +Maven:: ++ .pom.xml [source,xml,subs="verbatim,attributes"] ---- @@ -65,13 +99,27 @@ You can do so by adding a Maven property: ---- +Gradle:: ++ +.build.gradle +[source,groovy] +[subs="verbatim,attributes"] +---- +ext['spring.version']='{spring-core-version}' +---- +====== + If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies]. [[getting-maven-no-boot]] -=== Maven Without Spring Boot +=== Standalone Usage (Without Spring Boot) -When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure that a consistent version of Spring Security is used throughout the entire project. The following example shows how to do so: +When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure that a consistent version of Spring Security is used throughout the entire project. +[tabs] +====== +Maven:: ++ .pom.xml [source,xml,ubs="verbatim,attributes"] ---- @@ -89,8 +137,33 @@ When you use Spring Security without Spring Boot, the preferred way is to use Sp ---- +Gradle:: ++ +.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}' + } +} +---- +====== + +[TIP] +Spring provides a https://github.com/spring-gradle-plugins/dependency-management-plugin[`Dependency Management Plugin`] for Gradle + A minimal Spring Security Maven set of dependencies typically looks like the following example: +[tabs] +====== +Maven:: ++ .pom.xml [source,xml,subs="verbatim,attributes"] ---- @@ -107,12 +180,29 @@ A minimal Spring Security Maven set of dependencies typically looks like the fol ---- +Gradle:: ++ +.build.gradle +[source,groovy] +[subs="verbatim,attributes"] +---- +dependencies { + implementation "org.springframework.security:spring-security-web" + implementation "org.springframework.security:spring-security-config" +} +---- +====== + If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies]. Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x. Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems. -The easiest way to resolve this is to use the `spring-framework-bom` within the `` section of your `pom.xml`: +The easiest way to resolve this is to use the `spring-framework-bom` within the `` section of your `pom.xml` or your `dependencyManagement` section of your `build.gradle`. +[tabs] +====== +Maven:: ++ .pom.xml [source,xml,subs="verbatim,attributes"] ---- @@ -130,6 +220,27 @@ The easiest way to resolve this is to use the `spring-framework-bom` within the ---- +Gradle:: ++ +.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-core-version}' + } +} +---- +====== + +[TIP] +Spring provides a https://github.com/spring-gradle-plugins/dependency-management-plugin[`Dependency Management Plugin`] for Gradle + The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-core-version} modules. [NOTE] @@ -138,12 +249,26 @@ This approach uses Maven's "`bill of materials`" (BOM) concept and is only avail For additional details about how dependencies are resolved, see https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation]. ==== -[[maven-repositories]] +[[maven-gearepositories]] === Maven Repositories -All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so you need not declare additional Maven repositories in your pom. +All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so you need not declare additional Maven repositories in your `pom.xml`. + +For Gradle using the `mavenCentral()` repository is sufficient for GA releases. + +.build.gradle +[source,groovy] +---- +repositories { + mavenCentral() +} +---- If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined: +[tabs] +====== +Maven:: ++ .pom.xml [source,xml] ---- @@ -157,8 +282,23 @@ If you use a SNAPSHOT version, you need to ensure that you have the Spring Snaps ---- +Gradle:: ++ +.build.gradle +[source,groovy] +---- +repositories { + maven { url 'https://repo.spring.io/snapshot' } +} +---- +====== + 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: +[tabs] +====== +Maven:: ++ .pom.xml [source,xml] ---- @@ -172,132 +312,8 @@ If you use a milestone or release candidate version, you need to ensure that you ---- -[[getting-gradle]] -== Gradle - -As most open source projects, Spring Security deploys its dependencies as Maven artifacts, which allows for first-class Gradle support. -The following topics describe how to consume Spring Security when using Gradle. - -[[getting-gradle-boot]] -=== Spring Boot with Gradle - -Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies. -The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/html/[Spring Initializr] by using an IDE integration in (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse] or 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, you can manually add the starter: - -.build.gradle -[source,groovy] -[subs="verbatim,attributes"] ----- -dependencies { - implementation "org.springframework.boot:spring-boot-starter-security" -} ----- - -Since Spring Boot provides a Maven BOM to manage dependency versions, you need not specify a version. -If you wish to override the Spring Security version, you can do so by providing a Gradle property: - -.build.gradle -[source,groovy] -[subs="verbatim,attributes"] ----- -ext['spring-security.version']='{spring-security-version}' ----- - -Since Spring Security makes breaking changes only in major releases, you can safely use a newer version of Spring Security with Spring Boot. -However, at times, you may need to update the version of Spring Framework as well. -You can do so by adding a Gradle property: - -.build.gradle -[source,groovy] -[subs="verbatim,attributes"] ----- -ext['spring.version']='{spring-core-version}' ----- - -If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies]. - -=== Gradle Without Spring Boot - -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. -You can do so 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 { - implementation "org.springframework.security:spring-security-web" - implementation "org.springframework.security:spring-security-config" -} ----- - -If you use additional features (such as LDAP, OAuth 2, and others), you need to also include the appropriate xref:modules.adoc#modules[Project Modules and Dependencies]. - -Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x. -Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-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 `build.gradle`. -You can do so 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-core-version}' - } -} ----- - -The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-core-version} modules. - -[[gradle-repositories]] -=== Gradle Repositories -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: - -.build.gradle -[source,groovy] ----- -repositories { - mavenCentral() -} ----- - -If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined: - -.build.gradle -[source,groovy] ----- -repositories { - maven { url 'https://repo.spring.io/snapshot' } -} ----- - -If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined: - +Gradle:: ++ .build.gradle [source,groovy] ---- @@ -305,3 +321,5 @@ repositories { maven { url 'https://repo.spring.io/milestone' } } ---- +====== + From f4fcc3046a43668e38630519701c69b788d66c37 Mon Sep 17 00:00:00 2001 From: Josh Cummings <3627351+jzheaux@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:45:02 -0700 Subject: [PATCH 2/3] Polish Issue gh-16228 --- docs/modules/ROOT/pages/getting-spring-security.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/modules/ROOT/pages/getting-spring-security.adoc b/docs/modules/ROOT/pages/getting-spring-security.adoc index 22766a41423..35f87781ede 100644 --- a/docs/modules/ROOT/pages/getting-spring-security.adoc +++ b/docs/modules/ROOT/pages/getting-spring-security.adoc @@ -249,9 +249,9 @@ This approach uses Maven's "`bill of materials`" (BOM) concept and is only avail For additional details about how dependencies are resolved, see https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation]. ==== -[[maven-gearepositories]] +[[maven-repositories]] === Maven Repositories -All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so you need not declare additional Maven repositories in your `pom.xml`. +All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so you need not declare additional Maven repositories in your build configuration. For Gradle using the `mavenCentral()` repository is sufficient for GA releases. From f19801542c87f257c096df6076485ea6fb1874a9 Mon Sep 17 00:00:00 2001 From: Josh Cummings <3627351+jzheaux@users.noreply.github.com> Date: Tue, 10 Dec 2024 15:49:54 -0700 Subject: [PATCH 3/3] Update GA Release Guidance --- docs/modules/ROOT/pages/getting-spring-security.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/getting-spring-security.adoc b/docs/modules/ROOT/pages/getting-spring-security.adoc index 35f87781ede..ec6916a5dd8 100644 --- a/docs/modules/ROOT/pages/getting-spring-security.adoc +++ b/docs/modules/ROOT/pages/getting-spring-security.adoc @@ -251,7 +251,7 @@ For additional details about how dependencies are resolved, see https://maven.ap [[maven-repositories]] === Maven Repositories -All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so you need not declare additional Maven repositories in your build configuration. +All https://github.com/spring-projects/spring-security/wiki/Release-Schedule-Guidelines[GA releases] are deployed to Maven Central, so you need not declare additional Maven repositories in your build configuration. For Gradle using the `mavenCentral()` repository is sufficient for GA releases.