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

[[get-spring-security]]
= Getting Spring Security

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

Spring Security versions are formatted as MAJOR.MINOR.PATCH such that

* MAJOR versions may contain breaking changes.
Typically these are done to provide improved security to match modern security practices.
* MINOR versions contain enhancements, but are considered passive updates
* PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes which are to fix bugs


[[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
[source,xml]
[subs="verbatim,attributes"]
----
<dependencies>
	<!-- ... other dependency elements ... -->
	<dependency>
		<groupId>org.springframework.security</groupId>
		<artifactId>spring-security-web</artifactId>
	</dependency>
	<dependency>
		<groupId>org.springframework.security</groupId>
		<artifactId>spring-security-config</artifactId>
	</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.

If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:

.pom.xml
[source,xml]
----
<repositories>
	<!-- ... possibly other repository elements ... -->
	<repository>
		<id>spring-snapshot</id>
		<name>Spring Snapshot Repository</name>
		<url>https://repo.spring.io/snapshot</url>
	</repository>
</repositories>
----

If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:

.pom.xml
[source,xml]
----
<repositories>
	<!-- ... possibly other repository elements ... -->
	<repository>
		<id>spring-milestone</id>
		<name>Spring Milestone Repository</name>
		<url>https://repo.spring.io/milestone</url>
	</repository>
</repositories>
----


[[gradle]]
== Gradle

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.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 <<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"
	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.

.build.gradle
[source,groovy]
----
repositories {
	mavenCentral()
}
----

If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository defined as shown below:

.build.gradle
[source,groovy]
----
repositories {
	maven { url 'https://repo.spring.io/snapshot' }
}
----

If you are using a milestone or release candidate version, you will need to ensure you have the Spring Milestone repository defined as shown below:

.build.gradle
[source,groovy]
----
repositories {
	maven { url 'https://repo.spring.io/milestone' }
}
----