<commit_before>[[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.


== 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

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

[[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>http://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>http://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.

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:

.pom.xml
[source,xml]
[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>
----

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:

.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}'
}
----

If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate <<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' }
}
----

[[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.
<commit_msg>Polish Getting Spring Security Reference<commit_after>[[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' }
}
----

{'fraction_non_alphanumeric': 0.10512732278045424, 'fraction_numerical': 0.002007341133287451, 'mean_word_length': 4.676106770833333, 'pattern_counts': {'":': 0, '<': 168, '<?xml version=': 0, '>': 169, 'https://': 16, 'lorem ipsum': 0, 'www.': 3, 'xml': 27}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2018012', 'n_tokens_mistral': 4971, 'n_tokens_neox': 4594, 'n_words': 1790}