

[[introduction]]
== Introduction


[[what-is-acegi-security]]
=== What is Spring Security?
Spring Security provides comprehensive security services for Java EE-based enterprise software applications.
There is a particular emphasis on supporting projects built using The Spring Framework, which is the leading Java EE solution for enterprise software development.
If you're not using Spring for developing enterprise applications, we warmly encourage you to take a closer look at it.
Some familiarity with Spring - and in particular dependency injection principles - will help you get up to speed with Spring Security more easily.

People use Spring Security for many reasons, but most are drawn to the project after finding the security features of Java EE's Servlet Specification or EJB Specification lack the depth required for typical enterprise application scenarios.
Whilst mentioning these standards, it's important to recognise that they are not portable at a WAR or EAR level.
Therefore, if you switch server environments, it is typically a lot of work to reconfigure your application's security in the new target environment.
Using Spring Security overcomes these problems, and also brings you dozens of other useful, customisable security features.

As you probably know two major areas of application security are "authentication" and "authorization" (or "access-control").
These are the two main areas that Spring Security targets.
"Authentication" is the process of establishing a principal is who they claim to be (a "principal" generally means a user, device or some other system which can perform an action in your application).
"Authorization" refers to the process of deciding whether a principal is allowed to perform an action within your application.
To arrive at the point where an authorization decision is needed, the identity of the principal has already been established by the authentication process.
These concepts are common, and not at all specific to Spring Security.

At an authentication level, Spring Security supports a wide range of authentication models.
Most of these authentication models are either provided by third parties, or are developed by relevant standards bodies such as the Internet Engineering Task Force.
In addition, Spring Security provides its own set of authentication features.
Specifically, Spring Security currently supports authentication integration with all of these technologies:


* HTTP BASIC authentication headers (an IETF RFC-based standard)

* HTTP Digest authentication headers (an IETF RFC-based standard)

* HTTP X.509 client certificate exchange (an IETF RFC-based standard)

* LDAP (a very common approach to cross-platform authentication needs, especially in large environments)

* Form-based authentication (for simple user interface needs)

* OpenID authentication

* Authentication based on pre-established request headers (such as Computer Associates Siteminder)

* Jasig Central Authentication Service (otherwise known as CAS, which is a popular open source single sign-on system)

* Transparent authentication context propagation for Remote Method Invocation (RMI) and HttpInvoker (a Spring remoting protocol)

* Automatic "remember-me" authentication (so you can tick a box to avoid re-authentication for a predetermined period of time)

* Anonymous authentication (allowing every unauthenticated call to automatically assume a particular security identity)

* Run-as authentication (which is useful if one call should proceed with a different security identity)

* Java Authentication and Authorization Service (JAAS)

* Java EE container authentication (so you can still use Container Managed Authentication if desired)

* Kerberos

* Java Open Source Single Sign-On (JOSSO) *

* OpenNMS Network Management Platform *

* AppFuse *

* AndroMDA *

* Mule ESB *

* Direct Web Request (DWR) *

* Grails *

* Tapestry *

* JTrac *

* Jasypt *

* Roller *

* Elastic Path *

* Atlassian Crowd *

* Your own authentication systems (see below)



(* Denotes provided by a third party)

Many independent software vendors (ISVs) adopt Spring Security because of this significant choice of flexible authentication models.
Doing so allows them to quickly integrate their solutions with whatever their end clients need, without undertaking a lot of engineering or requiring the client to change their environment.
If none of the above authentication mechanisms suit your needs, Spring Security is an open platform and it is quite simple to write your own authentication mechanism.
Many corporate users of Spring Security need to integrate with "legacy" systems that don't follow any particular security standards, and Spring Security is happy to "play nicely" with such systems.

Irrespective of the authentication mechanism, Spring Security provides a deep set of authorization capabilities.
There are three main areas of interest: authorizing web requests, authorizing whether methods can be invoked and authorizing access to individual domain object instances.
To help you understand the differences, consider the authorization capabilities found in the Servlet Specification web pattern security, EJB Container Managed Security and file system security respectively.
Spring Security provides deep capabilities in all of these important areas, which we'll explore later in this reference guide.


[[history]]
=== History
Spring Security began in late 2003 as "The Acegi Security System for Spring".
A question was posed on the Spring Developers' mailing list asking whether there had been any consideration given to a Spring-based security implementation.
At the time the Spring community was relatively small (especially compared with the size today!), and indeed Spring itself had only existed as a SourceForge project from early 2003.
The response to the question was that it was a worthwhile area, although a lack of time currently prevented its exploration.

With that in mind, a simple security implementation was built and not released.
A few weeks later another member of the Spring community inquired about security, and at the time this code was offered to them.
Several other requests followed, and by January 2004 around twenty people were using the code.
These pioneering users were joined by others who suggested a SourceForge project was in order, which was duly established in March 2004.

In those early days, the project didn't have any of its own authentication modules.
Container Managed Security was relied upon for the authentication process, with Acegi Security instead focusing on authorization.
This was suitable at first, but as more and more users requested additional container support, the fundamental limitation of container-specific authentication realm interfaces became clear.
There was also a related issue of adding new JARs to the container's classpath, which was a common source of end user confusion and misconfiguration.

Acegi Security-specific authentication services were subsequently introduced.
Around a year later, Acegi Security became an official Spring Framework subproject.
The 1.
0.
0 final release was published in May 2006 - after more than two and a half years of active use in numerous production software projects and many hundreds of improvements and community contributions.

Acegi Security became an official Spring Portfolio project towards the end of 2007 and was rebranded as "Spring Security".

Today Spring Security enjoys a strong and active open source community.
There are thousands of messages about Spring Security on the support forums.
There is an active core of developers who work on the code itself and an active community which also regularly share patches and support their peers.


[[release-numbering]]
=== Release Numbering
It is useful to understand how Spring Security release numbers work, as it will help you identify the effort (or lack thereof) involved in migrating to future releases of the project.
Each release uses a standard triplet of integers: MAJOR.MINOR.PATCH.
The intent is that MAJOR versions are incompatible, large-scale upgrades of the API.
MINOR versions should largely retain source and binary compatibility with older minor versions, thought there may be some design changes and incompatible updates.
PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes which are to fix bugs and defects.

The extent to which you are affected by changes will depend on how tightly integrated your code is.
If you are doing a lot of customization you are more likely to be affected than if you are using a simple namespace configuration.

You should always test your application thoroughly before rolling out a new version.


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

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

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.

[[modules]]
==== Project Modules
In Spring Security 3.0, the codebase has been sub-divided into separate jars which more clearly separate different functionality areas and third-party dependencies.
If you are using Maven to build your project, then these are the modules you will add to your `pom.xml`.
Even if you're not using Maven, we'd recommend that you consult the `pom.xml` files to get an idea of third-party dependencies and versions.
Alternatively, a good idea is to examine the libraries that are included in the sample applications.


[[spring-security-core]]
===== Core - spring-security-core.jar
Contains core authentication and access-contol classes and interfaces, remoting support and basic provisioning APIs.
Required by any application which uses Spring Security.
Supports standalone applications, remote clients, method (service layer) security and JDBC user provisioning.
Contains the top-level packages:

* `org.springframework.security.core`

* `org.springframework.security.access`

* `org.springframework.security.authentication`

* `org.springframework.security.provisioning`





[[spring-security-remoting]]
===== Remoting - spring-security-remoting.jar
Provides intergration with Spring Remoting.
You don't need this unless you are writing a remote client which uses Spring Remoting.
The main package is `org.springframework.security.remoting`.


[[spring-security-web]]
===== Web - spring-security-web.jar
Contains filters and related web-security infrastructure code.
Anything with a servlet API dependency.
You'll need it if you require Spring Security web authentication services and URL-based access-control.
The main package is `org.springframework.security.web`.


[[spring-security-config]]
===== Config - spring-security-config.jar
Contains the security namespace parsing code & Java configuration code.
You need it if you are using the Spring Security XML namespace for configuration or Spring Security's Java Configuration support.
The main package is `org.springframework.security.config`.
None of the classes are intended for direct use in an application.


[[spring-security-ldap]]
===== LDAP - spring-security-ldap.jar
LDAP authentication and provisioning code.
Required if you need to use LDAP authentication or manage LDAP user entries.
The top-level package is `org.springframework.security.ldap`.


[[spring-security-oauth2-core]]
===== OAuth 2.0 Core - spring-security-oauth2-core.jar
`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the _OAuth 2.0 Authorization Framework_ and for _OpenID Connect Core 1.0_.
It is required by applications that use _OAuth 2.0_ or _OpenID Connect Core 1.0_, such as Client, Resource Server, and Authorization Server.
The top-level package is `org.springframework.security.oauth2.core`.


[[spring-security-oauth2-client]]
===== OAuth 2.0 Client - spring-security-oauth2-client.jar
`spring-security-oauth2-client.jar` is Spring Security's client support for _OAuth 2.0 Authorization Framework_ and _OpenID Connect Core 1.0_.
Required by applications leveraging *OAuth 2.0 Login* and/or OAuth Client support.
The top-level package is `org.springframework.security.oauth2.client`.


[[spring-security-oauth2-jose]]
===== OAuth 2.0 JOSE - spring-security-oauth2-jose.jar
`spring-security-oauth2-jose.jar` contains Spring Security's support for the _JOSE_ (Javascript Object Signing and Encryption) framework.
The _JOSE_ framework is intended to provide a method to securely transfer claims between parties.
It is built from a collection of specifications:

* JSON Web Token (JWT)
* JSON Web Signature (JWS)
* JSON Web Encryption (JWE)
* JSON Web Key (JWK)

It contains the top-level packages:

* `org.springframework.security.oauth2.jwt`
* `org.springframework.security.oauth2.jose`


[[spring-security-acl]]
===== ACL - spring-security-acl.jar
Specialized domain object ACL implementation.
Used to apply security to specific domain object instances within your application.
The top-level package is `org.springframework.security.acls`.


[[spring-security-cas]]
===== CAS - spring-security-cas.jar
Spring Security's CAS client integration.
If you want to use Spring Security web authentication with a CAS single sign-on server.
The top-level package is `org.springframework.security.cas`.


[[spring-security-openid]]
===== OpenID - spring-security-openid.jar
OpenID web authentication support.
Used to authenticate users against an external OpenID server.
`org.springframework.security.openid`.
Requires OpenID4Java.


[[spring-security-test]]
===== Test - spring-security-test.jar
Support for testing with Spring Security.


[[get-source]]
==== Checking out the Source
Since Spring Security is an Open Source project, we'd strongly encourage you to check out the source code using git.
This will give you full access to all the sample applications and you can build the most up to date version of the project easily.
Having the source for a project is also a huge help in debugging.
Exception stack traces are no longer obscure black-box issues but you can get straight to the line that's causing the problem and work out what's happening.
The source is the ultimate documentation for a project and often the simplest place to find out how something actually works.

To obtain the source for the project, use the following git command:

[source,txt]
----
git clone https://github.com/spring-projects/spring-security.git
----

This will give you access to the entire project history (including all releases and branches) on your local machine.
