0% found this document useful (0 votes)

1K views

Spring Security Reference

Uploaded by

Mamata Harish

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

1K views

Spring Security Reference

Uploaded by

Mamata Harish

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 242

Spring Security Reference

4.0.2.RELEASE

Ben Alex , Luke Taylor , Rob Winch , Gunnar Hillert

Copyright 2004-2015
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee
for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.

Spring Security Reference

Table of Contents
................................................................................................................................................ xv
I. Preface ................................................................................................................................... 1
II. Getting Started ....................................................................................................................... 3
1. Introduction .................................................................................................................... 4
1.1. What is Spring Security? ..................................................................................... 4
1.2. History ................................................................................................................ 6
1.3. Release Numbering ............................................................................................. 6
1.4. Getting Spring Security ........................................................................................ 7
Usage with Maven ............................................................................................. 7
Maven Repositories .................................................................................... 7
Spring Framework Bom .............................................................................. 8
Gradle ............................................................................................................... 8
Gradle Repositories .................................................................................... 8
Using Spring 4.0.x and Gradle .................................................................... 9
Project Modules ................................................................................................. 9
Core - spring-security-core.jar ..................................................................... 9
Remoting - spring-security-remoting.jar ...................................................... 10
Web - spring-security-web.jar .................................................................... 10
Config - spring-security-config.jar .............................................................. 10
LDAP - spring-security-ldap.jar .................................................................. 10
ACL - spring-security-acl.jar ...................................................................... 10
CAS - spring-security-cas.jar ..................................................................... 10
OpenID - spring-security-openid.jar ............................................................ 10
Checking out the Source .................................................................................. 10
2. Whats new in Spring Security 4.0 ................................................................................. 12
2.1. Features ............................................................................................................ 12
2.2. Migrating from 3.x to 4.x .................................................................................... 12
3. Java Configuration ....................................................................................................... 14
3.1. Hello Web Security Java Configuration ............................................................... 14
AbstractSecurityWebApplicationInitializer ........................................................... 15
AbstractSecurityWebApplicationInitializer without Existing Spring ......................... 15
AbstractSecurityWebApplicationInitializer with Spring MVC ................................. 16
3.2. HttpSecurity ....................................................................................................... 16
3.3. Java Configuration and Form Login .................................................................... 17
3.4. Authorize Requests ........................................................................................... 18
3.5. Handling Logouts ............................................................................................... 19
LogoutHandler .................................................................................................. 20
LogoutSuccessHandler ..................................................................................... 20
Further Logout-Related References ................................................................... 20
3.6. Authentication .................................................................................................... 21
In Memory Authentication ................................................................................. 21
JDBC Authentication ......................................................................................... 21
LDAP Authentication ......................................................................................... 21
3.7. Multiple HttpSecurity .......................................................................................... 22
3.8. Method Security ................................................................................................ 23
EnableGlobalMethodSecurity ............................................................................. 23
GlobalMethodSecurityConfiguration ................................................................... 24

11. The Security Filter Chain ............................................................................................

11.1. DelegatingFilterProxy .......................................................................................
11.2. FilterChainProxy ..............................................................................................
Bypassing the Filter Chain ................................................................................
11.3. Filter Ordering .................................................................................................
11.4. Request Matching and HttpFirewall ...................................................................
11.5. Use with other Filter-Based Frameworks ...........................................................
11.6. Advanced Namespace Configuration .................................................................
12. Core Security Filters ...................................................................................................
12.1. FilterSecurityInterceptor ....................................................................................
12.2. ExceptionTranslationFilter .................................................................................
AuthenticationEntryPoint ...................................................................................
AccessDeniedHandler .......................................................................................
SavedRequest s and the RequestCache Interface ..............................................
12.3. SecurityContextPersistenceFilter .......................................................................
SecurityContextRepository ................................................................................
12.4. UsernamePasswordAuthenticationFilter .............................................................
Application Flow on Authentication Success and Failure .....................................
13. Servlet API integration ................................................................................................
13.1. Servlet 2.5+ Integration ....................................................................................
HttpServletRequest.getRemoteUser() ................................................................
HttpServletRequest.getUserPrincipal() ...............................................................
HttpServletRequest.isUserInRole(String) ............................................................
13.2. Servlet 3+ Integration .......................................................................................
HttpServletRequest.authenticate(HttpServletRequest,HttpServletResponse) .........
HttpServletRequest.login(String,String) ..............................................................
HttpServletRequest.logout() ...............................................................................
AsyncContext.start(Runnable) ...........................................................................
Async Servlet Support ......................................................................................
13.3. Servlet 3.1+ Integration ....................................................................................
HttpServletRequest#changeSessionId() .............................................................
14. Basic and Digest Authentication ..................................................................................
14.1. BasicAuthenticationFilter ..................................................................................
Configuration ....................................................................................................
14.2. DigestAuthenticationFilter .................................................................................
Configuration ....................................................................................................
15. Remember-Me Authentication .....................................................................................
15.1. Overview .........................................................................................................
15.2. Simple Hash-Based Token Approach ................................................................
15.3. Persistent Token Approach ..............................................................................
15.4. Remember-Me Interfaces and Implementations .................................................
TokenBasedRememberMeServices ...................................................................
PersistentTokenBasedRememberMeServices .....................................................
16. Cross Site Request Forgery (CSRF) ............................................................................
16.1. CSRF Attacks ..................................................................................................
16.2. Synchronizer Token Pattern .............................................................................
16.3. When to use CSRF protection ..........................................................................
CSRF protection and JSON ..............................................................................
CSRF and Stateless Browser Applications .........................................................
16.4. Using Spring Security CSRF Protection .............................................................

4.0.2.RELEASE

Spring Security

74
74
74
75
76
76
77
77
79
79
80
80
80
81
81
82
82
83
84
84
84
84
84
85
85
85
85
85
86
87
87
88
88
88
88
89
91
91
91
92
92
92
93
94
94
94
95
95
95
96

Spring Security Reference

17.

18.

19.

20.

Use proper HTTP verbs .................................................................................... 96

1.2 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 didnt 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 containers 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.

1.3 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, largescale 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.

4.0.2.RELEASE

Spring Security

Spring Security Reference

1.4 Getting Spring Security

You can get hold of Spring Security in several ways. You can download a packaged distribution
from the main Spring Security page, download individual jars from the Maven Central repository (or a
SpringSource Maven repository for snapshot and milestone releases) or, alternatively, you can build
the project from source yourself.

Usage with Maven

A minimal Spring Security Maven set of dependencies typically looks like the following:
pom.xml.
<dependencies>

<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-web</artifactId>
<version>4.0.2.RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-config</artifactId>
<version>4.0.2.RELEASE</version>
</dependency>
</dependencies>

If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate
the section called Project Modules.
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.
<repositories>

<repository>
<id>spring-snapshot</id>
<name>Spring Snapshot Repository</name>
<url>http://repo.springsource.org/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.
<repositories>

<repository>
<id>spring-milestone</id>
<name>Spring Milestone Repository</name>
<url>http://repo.springsource.org/milestone</url>
</repository>
</repositories>

4.0.2.RELEASE

Spring Security

Spring Security Reference

Spring Framework Bom

Spring Security builds against Spring Framework 4.1.6.RELEASE, but should work with 4.0.x. The
problem that many users will have is that Spring Securitys transitive dependencies resolve Spring
Framework 4.1.6.RELEASE which can cause strange classpath problems.
One (tedious) way to circumvent this issue would be to include all the Spring Framework modules in
a <dependencyManagement> section of your pom. An alternative approach is to include the springframework-bom within your <dependencyManagement> section of your pom.xml as shown below:
pom.xml.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-framework-bom</artifactId>
<version>4.1.6.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

This will ensure that all the transitive dependencies of Spring Security use the Spring 4.1.6.RELEASE
modules.
Note
This approach uses Mavens "bill of materials" (BOM) concept and is only available in Maven
2.0.9+. For additional details about how dependencies are resolved refer to Mavens Introduction
to the Dependency Mechanism documentation.

Gradle
A minimal Spring Security Gradle set of dependencies typically looks like the following:
build.gradle.
dependencies {
compile 'org.springframework.security:spring-security-web:4.0.2.RELEASE'
compile 'org.springframework.security:spring-security-config:4.0.2.RELEASE'
}

If you are using additional features like LDAP, OpenID, etc. you will need to also include the appropriate
the section called Project Modules.
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.
repositories {
mavenCentral()
}

4.0.2.RELEASE

Spring Security

Spring Security Reference

If you are using a SNAPSHOT version, you will need to ensure you have the Spring Snapshot repository
defined as shown below:
build.gradle.
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.
repositories {
maven { url 'https://repo.spring.io/milestone' }
}

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 4.0.2.RELEASE with Spring
Framework 4.1.6.RELEASE. However, at times there can be issues that come up so it is best to mitigate
this using Gradles ResolutionStrategy as shown below:
build.gradle.
configurations.all {
resolutionStrategy.eachDependency { DependencyResolveDetails details ->
if (details.requested.group == 'org.springframework') {
details.useVersion '4.1.6.RELEASE'
}
}
}

This will ensure that all the transitive dependencies of Spring Security use the Spring 4.1.6.RELEASE
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.

Project Modules
In Spring Security 3.0, the codebase has been sub-divided into separate jars which more clearly
separate different functionaltiy 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 youre not using Maven, wed
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.
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:

4.0.2.RELEASE

Spring Security

Spring Security Reference

org.springframework.security.core
org.springframework.security.access
org.springframework.security.authentication
org.springframework.security.provisioning
Remoting - spring-security-remoting.jar
Provides intergration with Spring Remoting. You dont need this unless you are writing a remote client
which uses Spring Remoting. The main package is org.springframework.security.remoting.
Web - spring-security-web.jar
Contains filters and related web-security infrastructure code. Anything with a servlet API dependency.
Youll need it if you require Spring Security web authentication services and URL-based access-control.
The main package is org.springframework.security.web.
Config - spring-security-config.jar
Contains the security namespace parsing code. You need it if you are using the Spring Security XML
namespace for configuration. The main package is org.springframework.security.config.
None of the classes are intended for direct use in an application.
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.
ACL - spring-security-acl.jar
Specialized
domain
object
ACL
implementation.
Used
to
specific domain object instances within your application. The
org.springframework.security.acls.

apply
security
top-level package

to
is

CAS - spring-security-cas.jar
Spring Securitys 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.
OpenID - spring-security-openid.jar
OpenID web authentication support. Used to authenticate users against an external OpenID server.
org.springframework.security.openid. Requires OpenID4Java.

Checking out the Source

Since Spring Security is an Open Source project, wed 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 thats
causing the problem and work out whats 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:

4.0.2.RELEASE

Spring Security

Spring Security Reference

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.

4.0.2.RELEASE

Spring Security

Spring Security Reference

2. Whats new in Spring Security 4.0

There are 175+ tickets resolved with the Spring Security 4.0 release.

2.1 Features
Below are the highlights of the new features found in Spring Security 4.0.
Web Socket Support
Test Support
Spring Data Integration
CSRF Token Argument Resolver
More Secure Defaults
Methods with role in them do not require ROLE_ For example, previously the following would be
required within XML configuration:
<intercept-url pattern="/**" access="hasRole('ROLE_USER')"/>

Now you can optionally omit the ROLE_ prefix. We do this to remove duplication. Specifically, since
the expression hasRole already defines the value as a role it automatically adds the prefix if it is not
there. For example, the following is the same as the previous configuration:
<intercept-url pattern="/**" access="hasRole('USER')"/>

Similarly, the following configuration:

@PreAuthorize("hasRole('ROLE_USER')")

is the same as this more concise configuration:

@PreAuthorize("hasRole('USER')")

Many Integration Tests Added to Samples

Deprecate @EnableWebMvcSecurity - by updating the minimum Spring Version, we can now allow
defaulting MVC integration with @EnableWebSecurity but still allow it to be overridden

2.2 Migrating from 3.x to 4.x

As exploits against applications evolve, so must Spring Security. As a major release version, the Spring
Security team took the opportunity to make some non-passive changes which focus on:
Ensuring Spring Security is more secure by default
Minimizing Information Leakage
Removing deprecated APIs
For complete details on migrating from Spring Security 3 to Spring Security 4 refer to one of the guides
below:

4.0.2.RELEASE

Spring Security

Spring Security Reference

Migrating from Spring Security 3.x to 4.x (XML Configuration)

Migrating from Spring Security 3.x to 4.x (Java Configuration)

4.0.2.RELEASE

Spring Security

Spring Security Reference

3. Java Configuration
General support for Java Configuration was added to Spring framework in Spring 3.1. Since Spring
Security 3.2 there has been Spring Security Java Configuration support which enables users to easily
configure Spring Security without the use of any XML.
If you are familiar with the Chapter 4, Security Namespace Configuration then you should find quite a
few similarities between it and the Security Java Configuration support.
Note
Spring Security provides lots of sample applications that end in -jc which demonstrate the use
of Spring Security Java Configuration.

3.1 Hello Web Security Java Configuration

The first step is to create our Spring Security Java Configuration. The configuration creates a Servlet
Filter known as the springSecurityFilterChain which is responsible for all the security (protecting
the application URLs, validating submitted username and passwords, redirecting to the log in form, etc)
within your application. You can find the most basic example of a Spring Security Java configuration
below:
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.*;
import org.springframework.security.config.annotation.authentication.builders.*;
import org.springframework.security.config.annotation.web.configuration.*;
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth
.inMemoryAuthentication()
.withUser("user").password("password").roles("USER");
}
}

Note
The name of the configureGlobal method is not important. However, it is important to only
configure AuthenticationManagerBuilder in a class annotated with either @EnableWebSecurity,
@EnableGlobalMethodSecurity, or @EnableGlobalAuthentication. Doing otherwise
has unpredictable results.
There really isnt much to this configuration, but it does a lot. You can find a summary of the features
below:
Require authentication to every URL in your application
Generate a login form for you
Allow the user with the Username user and the Password password to authenticate with form based
authentication
Allow the user to logout

4.0.2.RELEASE

Spring Security

Spring Security Reference

CSRF attack prevention

Session Fixation protection
Security Header integration
HTTP Strict Transport Security for secure requests
X-Content-Type-Options integration
Cache Control (can be overridden later by your application to allow caching of your static resources)
X-XSS-Protection integration
X-Frame-Options integration to help prevent Clickjacking
Integrate with the following Servlet API methods
HttpServletRequest#getRemoteUser()
HttpServletRequest.html#getUserPrincipal()
HttpServletRequest.html#isUserInRole(java.lang.String)
HttpServletRequest.html#login(java.lang.String, java.lang.String)
HttpServletRequest.html#logout()

AbstractSecurityWebApplicationInitializer
The next step is to register the springSecurityFilterChain with the war.
This can be done in Java Configuration with Springs WebApplicationInitializer
support in a Servlet 3.0+ environment. Not suprisingly, Spring Security provides
a base class AbstractSecurityWebApplicationInitializer that will ensure the
springSecurityFilterChain gets registered for you. The way in which we use
AbstractSecurityWebApplicationInitializer differs depending on if we are already using
Spring or if Spring Security is the only Spring component in our application.
the section called AbstractSecurityWebApplicationInitializer without Existing Spring - Use these
instructions if you are not using Spring already
the section called AbstractSecurityWebApplicationInitializer with Spring MVC - Use these
instructions if you are already using Spring

AbstractSecurityWebApplicationInitializer without Existing Spring

If you are not using Spring or Spring MVC, you will need to pass in the SecurityConfig into the
superclass to ensure the configuration is picked up. You can find an example below:
import org.springframework.security.web.context.*;
public class SecurityWebApplicationInitializer
extends AbstractSecurityWebApplicationInitializer {
public SecurityWebApplicationInitializer() {
super(SecurityConfig.class);
}
}

4.0.2.RELEASE

Spring Security

Spring Security Reference

The SecurityWebApplicationInitializer will do the following things:

Automatically register the springSecurityFilterChain Filter for every URL in your application
Add a ContextLoaderListener that loads the SecurityConfig.

AbstractSecurityWebApplicationInitializer with Spring MVC

If we were using Spring elsewhere in our application we probably already had a
WebApplicationInitializer that is loading our Spring Configuration. If we use the
previous configuration we would get an error. Instead, we should register Spring Security
with the existing ApplicationContext. For example, if we were using Spring MVC our
SecurityWebApplicationInitializer would look something like the following:
import org.springframework.security.web.context.*;
public class SecurityWebApplicationInitializer
extends AbstractSecurityWebApplicationInitializer {
}

This would simply only register the springSecurityFilterChain Filter for every URL in your application.
After that we would ensure that SecurityConfig was loaded in our existing ApplicationInitializer. For
example, if we were using Spring MVC it would be added in the getRootConfigClasses()
public class MvcWebApplicationInitializer extends
AbstractAnnotationConfigDispatcherServletInitializer {
@Override
protected Class<?>[] getRootConfigClasses() {
return new Class[] { SecurityConfig.class };
}
// ... other overrides ...
}

3.2 HttpSecurity
Thus far our SecurityConfig only contains information about how to authenticate our users.
How does Spring Security know that we want to require all users to be authenticated? How
does Spring Security know we want to support form based authentication? The reason for
this is that the WebSecurityConfigurerAdapter provides a default configuration in the
configure(HttpSecurity http) method that looks like:
protected void configure(HttpSecurity http) throws Exception {
http
.authorizeRequests()
.anyRequest().authenticated()
.and()
.formLogin()
.and()
.httpBasic();
}

The default configuration above:

Ensures that any request to our application requires the user to be authenticated
Allows users to authenticate with form based login

4.0.2.RELEASE

Spring Security

Spring Security Reference

Allows users to authenticate with HTTP Basic authentication

You will notice that this configuration is quite similar the XML Namespace configuration:
<http>
<intercept-url pattern="/**" access="authenticated"/>
<form-login />
<http-basic />
</http>

The Java Configuration equivalent of closing an XML tag is expressed using the and() method which
allows us to continue configuring the parent. If you read the code it also makes sense. I want to configure
authorized requests and configure form login and configure HTTP Basic authentication.
However, Java configuration has different defaults URLs and parameters. Keep this in mind when
creating custom login pages. The result is that our URLs are more RESTful. Additionally, it is not quite
so obvious we are using Spring Security which helps to prevent information leaks. For example:

3.3 Java Configuration and Form Login

You might be wondering where the login form came from when you were prompted to log in, since
we made no mention of any HTML files or JSPs. Since Spring Securitys default configuration does
not explicitly set a URL for the login page, Spring Security generates one automatically, based on the
features that are enabled and using standard values for the URL which processes the submitted login,
the default target URL the user will be sent to after logging in and so on.
While the automatically generated log in page is convenient to get up and running quickly, most
applications will want to provide their own log in page. To do so we can update our configuration as
seen below:
protected void configure(HttpSecurity http) throws Exception {
http
.authorizeRequests()
.anyRequest().authenticated()
.and()
.formLogin()
.loginPage("/login")
.permitAll();

The updated configuration specifies the location of the log in page.

We must grant all users (i.e. unauthenticated users) access to our log in page. The
formLogin().permitAll() method allows granting access to all users for all URLs associated
with form based log in.

An example log in page implemented with JSPs for our current configuration can be seen below:
Note
The login page below represents our current configuration. We could easily update our
configuration if some of the defaults do not meet our needs.

4.0.2.RELEASE

Spring Security

Spring Security Reference

<c:url value="/login" var="loginUrl"/>

<form action="${loginUrl}" method="post">

<c:if test="${param.error != null}">
<p>
Invalid username and password.
</p>
</c:if>

<c:if test="${param.logout != null}">

<p>
You have been logged out.
</p>
</c:if>
<p>
<label for="username">Username</label>

<input type="text" id="username" name="username"/>

</p>
<p>
<label for="password">Password</label>
<input type="password" id="password" name="password"/>
</p>
<input type="hidden"

name="${_csrf.parameterName}"
value="${_csrf.token}"/>
<button type="submit" class="btn">Log in</button>
</form>

A POST to the /login URL will attempt to authenticate the user

If the query parameter error exists, authentication was attempted and failed

If the query parameter logout exists, the user was successfully logged out

The username must be present as the HTTP parameter named username

The password must be present as the HTTP parameter named password

We must the section called Include the CSRF Token To learn more read the Chapter 16, Cross
Site Request Forgery (CSRF) section of the reference

3.4 Authorize Requests

Our examples have only required users to be authenticated and have done so for every URL in our
application. We can specify custom requirements for our URLs by adding multiple children to our
http.authorizeRequests() method. For example:
protected void configure(HttpSecurity http) throws Exception {
http

.authorizeRequests()
.antMatchers("/resources/**", "/signup", "/about").permitAll()

.antMatchers("/admin/**").hasRole("ADMIN")

.antMatchers("/db/**").access("hasRole('ADMIN') and hasRole('DBA')")

.anyRequest().authenticated()
.and()
// ...
.formLogin();
}

There are multiple children to the http.authorizeRequests() method each matcher is

considered in the order they were declared.
We specified multiple URL patterns that any user can access. Specifically, any user can access a
request if the URL starts with "/resources/", equals "/signup", or equals "/about".
Any URL that starts with "/admin/" will be resticted to users who have the role "ROLE_ADMIN".
You will notice that since we are invoking the hasRole method we do not need to specify the
"ROLE_" prefix.

4.0.2.RELEASE

Spring Security

Spring Security Reference

Any URL that starts with "/db/" requires the user to have both "ROLE_ADMIN" and "ROLE_DBA".
You will notice that since we are using the hasRole expression we do not need to specify the
"ROLE_" prefix.
Any URL that has not already been matched on only requires that the user be authenticated

3.5 Handling Logouts

When using the WebSecurityConfigurerAdapter, logout capabilities are automatically applied.
The default is that accessing the URL /logout will log the user out by:
Invalidating the HTTP Session
Cleaning up any RememberMe authentication that was configured
Clearing the SecurityContextHolder
Redirect to /login?success
Similar to configuring login capabilities, however, you also have various options to further customize
your logout requirements:
protected void configure(HttpSecurity http) throws Exception {
http

.logout()
.logoutUrl("/my/logout")

.logoutSuccessUrl("/my/index")

.logoutSuccessHandler(logoutSuccessHandler)

.invalidateHttpSession(true)

.addLogoutHandler(logoutHandler)

.deleteCookies(cookieNamesToClear)
.and()
...

Provides
logout
support.
This
is
automatically
applied
when
using
WebSecurityConfigurerAdapter.
The URL that triggers log out to occur (default is /logout). If CSRF protection is enabled (default),
then the request must also be a POST. For for information, please consult the JavaDoc.
The URL to redirect to after logout has occurred. The default is /login?logout. For for
information, please consult the JavaDoc.
Lets you specify a custom LogoutSuccessHandler. If this is specified, logoutSuccessUrl()
is ignored. For for information, please consult the JavaDoc.
Specify whether to invalidate the HttpSession at the time of logout. This is true by default.
Configures the SecurityContextLogoutHandler under the covers. For for information, please
consult the JavaDoc.
Adds a LogoutHandler. SecurityContextLogoutHandler is added as the last
LogoutHandler by default.
Allows specifying the names of cookies to be removed on logout success. This is a shortcut for
adding a CookieClearingLogoutHandler explicitly.

Note
Logouts can of course also be configured using the XML Namespace notation. Please see the
documentation for the logout element in the Spring Security XML Namespace section for further
details.

4.0.2.RELEASE

Spring Security

Spring Security Reference

Generally, in order to customize logout functionality, you can add LogoutHandler and/or
LogoutSuccessHandler implementations. For many common scenarios, these handlers are applied
under the covers when using the fluent API.

LogoutHandler
Generally, LogoutHandler implementations indicate classes that are able to participate in logout
handling. They are expected to be invoked to perform necessary cleanup. As such they should not throw
exceptions. Various implementations are provided:
PersistentTokenBasedRememberMeServices
TokenBasedRememberMeServices
CookieClearingLogoutHandler
CsrfLogoutHandler
SecurityContextLogoutHandler
Please see Section 15.4, Remember-Me Interfaces and Implementations for details.
Instead of providing LogoutHandler implementations directly, the fluent API also provides
shortcuts that provide the respective LogoutHandler implementations under the covers. E.g.
deleteCookies() allows specifying the names of one or more cookies to be removed on logout
success. This is a shortcut compared to adding a CookieClearingLogoutHandler.

LogoutSuccessHandler
The LogoutSuccessHandler is called after a successful logout by the LogoutFilter, to handle
e.g. redirection or forwarding to the appropriate destination. Note that the interface is almost the same
as the LogoutHandler but may raise an exception.
The following implementations are provided:
SimpleUrlLogoutSuccessHandler
HttpStatusReturningLogoutSuccessHandler
As mentioned above, you dont need to specify the SimpleUrlLogoutSuccessHandler directly.
Instead, the fluent API provides a shortcut by setting the logoutSuccessUrl(). This will setup the
SimpleUrlLogoutSuccessHandler under the covers. The provided URL will be redirected to after
a logout has occurred. The default is /login?logout.
The HttpStatusReturningLogoutSuccessHandler can be interesting in REST API type
scenarios. Instead of redirecting to a URL upon the successful logout, this LogoutSuccessHandler
allows you to provide a plain HTTP status code to be returned. If not configured a status code 200 will
be returned by default.

Further Logout-Related References

Logout Handling
Testing Logout
HttpServletRequest.logout()

4.0.2.RELEASE

Spring Security

Spring Security Reference

Section 15.4, Remember-Me Interfaces and Implementations

Logging Out in section CSRF Caveats
Section Single Logout (CAS protocol)
Documentation for the logout element in the Spring Security XML Namespace section

3.6 Authentication
Thus far we have only taken a look at the most basic authentication configuration. Lets take a look at
a few slightly more advanced options for configuring authentication.

In Memory Authentication
We have already seen an example of configuring in memory authentication for a single user. Below is
an example to configure multiple users:
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth
.inMemoryAuthentication()
.withUser("user").password("password").roles("USER").and()
.withUser("admin").password("password").roles("USER", "ADMIN");
}

JDBC Authentication
You can find the updates to suppport JDBC based authentication. The example below assumes that you
have already defined a DataSource within your application. The jdbc-jc sample provides a complete
example of using JDBC based authentication.
@Autowired
private DataSource dataSource;
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth
.jdbcAuthentication()
.dataSource(dataSource)
.withDefaultSchema()
.withUser("user").password("password").roles("USER").and()
.withUser("admin").password("password").roles("USER", "ADMIN");
}

LDAP Authentication
You can find the updates to suppport LDAP based authentication. The ldap-jc sample provides a
complete example of using LDAP based authentication.
@Autowired
private DataSource dataSource;
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
auth
.ldapAuthentication()
.userDnPatterns("uid={0},ou=people")
.groupSearchBase("ou=groups");
}

4.0.2.RELEASE

Spring Security

Spring Security Reference

The example above uses the following LDIF and an embedded Apache DS LDAP instance.
users.ldif.
dn: ou=groups,dc=springframework,dc=org
objectclass: top
objectclass: organizationalUnit
ou: groups
dn: ou=people,dc=springframework,dc=org
objectclass: top
objectclass: organizationalUnit
ou: people
dn: uid=admin,ou=people,dc=springframework,dc=org
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Rod Johnson
sn: Johnson
uid: admin
userPassword: password
dn: uid=user,ou=people,dc=springframework,dc=org
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Dianne Emu
sn: Emu
uid: user
userPassword: password
dn: cn=user,ou=groups,dc=springframework,dc=org
objectclass: top
objectclass: groupOfNames
cn: user
uniqueMember: uid=admin,ou=people,dc=springframework,dc=org
uniqueMember: uid=user,ou=people,dc=springframework,dc=org
dn: cn=admin,ou=groups,dc=springframework,dc=org
objectclass: top
objectclass: groupOfNames
cn: admin
uniqueMember: uid=admin,ou=people,dc=springframework,dc=org

3.7 Multiple HttpSecurity

We can configure multiple HttpSecurity instances just as we can have multiple <http> blocks. The key
is to extend the WebSecurityConfigurationAdapter multiple times. For example, the following is
an example of having a different configuration for URLs that start with /api/.

4.0.2.RELEASE

Spring Security

Spring Security Reference

@EnableWebSecurity
public class MultiHttpSecurityConfig {
@Autowired
public void configureGlobal(AuthenticationManagerBuilder auth) {
auth
.inMemoryAuthentication()
.withUser("user").password("password").roles("USER").and()
.withUser("admin").password("password").roles("USER", "ADMIN");
}
@Configuration
@Order(1)

public static class ApiWebSecurityConfigurationAdapter extends WebSecurityConfigurerAdapter {

protected void configure(HttpSecurity http) throws Exception {
http
.antMatcher("/api/**")
.authorizeRequests()
.anyRequest().hasRole("ADMIN")
.and()
.httpBasic();

}
}
@Configuration

public static class FormLoginWebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {

@Override
protected void configure(HttpSecurity http) throws Exception {
http
.authorizeRequests()
.anyRequest().authenticated()
.and()
.formLogin();
}
}
}

Configure Authentication as normal

Create an instance of WebSecurityConfigurerAdapter that contains @Order to specify which

WebSecurityConfigurerAdapter should be considered first.
The http.antMatcher states that this HttpSecurity will only be applicable to URLs that start
with /api/
Create another instance of WebSecurityConfigurerAdapter. If the URL does not
start with /api/ this configuration will be used. This configuration is considered after
ApiWebSecurityConfigurationAdapter since it has an @Order value after 1 (no @Order
defaults to last).

3.8 Method Security

From version 2.0 onwards Spring Security has improved support substantially for adding security to your
service layer methods. It provides support for JSR-250 annotation security as well as the framework###s
original @Secured annotation. From 3.0 you can also make use of new expression-based annotations.
You can apply security to a single bean, using the intercept-methods element to decorate the bean
declaration, or you can secure multiple beans across the entire service layer using the AspectJ style
pointcuts.

EnableGlobalMethodSecurity
We can enable annotation-based security using the @EnableGlobalMethodSecurity annotation on
any @Configuration instance. For example, the following would enable Spring Securitys @Secured
annotation.

4.0.2.RELEASE

Spring Security

Spring Security Reference

@EnableGlobalMethodSecurity(securedEnabled = true)
public class MethodSecurityConfig {
// ...
}

Adding an annotation to a method (on an class or interface) would then limit the access to that method
accordingly. Spring Securitys native annotation support defines a set of attributes for the method. These
will be passed to the AccessDecisionManager for it to make the actual decision:
public interface BankService {
@Secured("IS_AUTHENTICATED_ANONYMOUSLY")
public Account readAccount(Long id);
@Secured("IS_AUTHENTICATED_ANONYMOUSLY")
public Account[] findAccounts();
@Secured("ROLE_TELLER")
public Account post(Account account, double amount);
}

Support for JSR-250 annotations can be enabled using

@EnableGlobalMethodSecurity(jsr250Enabled = true)
public class MethodSecurityConfig {
// ...
}

These are standards-based and allow simple role-based constraints to be applied but do not have the
power Spring Securitys native annotations. To use the new expression-based syntax, you would use
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class MethodSecurityConfig {
// ...
}

and the equivalent Java code would be

public interface BankService {
@PreAuthorize("isAnonymous()")
public Account readAccount(Long id);
@PreAuthorize("isAnonymous()")
public Account[] findAccounts();
@PreAuthorize("hasAuthority('ROLE_TELLER')")
public Account post(Account account, double amount);
}

GlobalMethodSecurityConfiguration
Sometimes you may need to perform operations that are more complicated than are possible with
the @EnableGlobalMethodSecurity annotation allow. For these instances, you can extend the
GlobalMethodSecurityConfiguration ensuring that the @EnableGlobalMethodSecurity
annotation is present on your subclass. For example, if you wanted to provide a custom
MethodSecurityExpressionHander, you could use the following configuration:

4.0.2.RELEASE

Spring Security

Spring Security Reference

@EnableGlobalMethodSecurity(prePostEnabled = true)
public class MethodSecurityConfig extends GlobalMethodSecurityConfiguration {
@Override
protected MethodSecurityExpressionHandler createExpressionHandler() {
// ... create and return custom MethodSecurityExpressionHandler ...
return expressionHander;
}
}

For additional information about methods that

GlobalMethodSecurityConfiguration Javadoc.

can

overriden,

refer

the

3.9 Post Processing Configured Objects

4.0.2.RELEASE

Spring Security

Spring Security Reference

provider elements must be children of the <authentication-manager> element, which

creates a ProviderManager and registers the authentication providers with it. You can find more
detailed information on the beans that are created in the namespace appendix. Its worth crosschecking this if you want to start understanding what the important classes in the framework are
and how they are used, particularly if you want to customise things later.
The configuration above defines two users, their passwords and their roles within the application (which
will be used for access control). It is also possible to load user information from a standard properties
file using the properties attribute on user-service. See the section on in-memory authentication
for more details on the file format. Using the <authentication-provider> element means that the
user information will be used by the authentication manager to process authentication requests. You
can have multiple <authentication-provider> elements to define different authentication sources
and each will be consulted in turn.
At this point you should be able to start up your application and you will be required to log in to proceed.
Try it out, or try experimenting with the"tutorial" sample application that comes with the project.

Form and Basic Login Options

You might be wondering where the login form came from when you were prompted to log in, since we
made no mention of any HTML files or JSPs. In fact, since we didnt explicitly set a URL for the login
page, Spring Security generates one automatically, based on the features that are enabled and using
standard values for the URL which processes the submitted login, the default target URL the user will
be sent to after logging in and so on. However, the namespace offers plenty of support to allow you to
customize these options. For example, if you want to supply your own login page, you could use:
<http>
<intercept-url pattern="/login.jsp*" access="IS_AUTHENTICATED_ANONYMOUSLY"/>
<intercept-url pattern="/**" access="ROLE_USER" />
<form-login login-page='/login.jsp'/>
</http>

Also note that weve added an extra intercept-url element to say that any requests for the login
5
page should be available to anonymous users and also the AuthenticatedVoter class for more details
on how the value IS_AUTHENTICATED_ANONYMOUSLY is processed.]. Otherwise the request would be
matched by the pattern /** and it wouldnt be possible to access the login page itself! This is a common
configuration error and will result in an infinite loop in the application. Spring Security will emit a warning
in the log if your login page appears to be secured. It is also possible to have all requests matching a
particular pattern bypass the security filter chain completely, by defining a separate http element for
the pattern like this:
<http pattern="/css/**" security="none"/>
<http pattern="/login.jsp*" security="none"/>
<http use-expressions="false">
<intercept-url pattern="/**" access="ROLE_USER" />
<form-login login-page='/login.jsp'/>
</http>

From Spring Security 3.1 it is now possible to use multiple http elements to define separate security
filter chain configurations for different request patterns. If the pattern attribute is omitted from an http
element, it matches all requests. Creating an unsecured pattern is a simple example of this syntax,
5

See the chapter on Chapter 19, Anonymous Authentication

4.0.2.RELEASE

Spring Security

Spring Security Reference

where the pattern is mapped to an empty filter chain . Well look at this new syntax in more detail in
the chapter on the Security Filter Chain.
Its important to realise that these unsecured requests will be completely oblivious to any Spring
Security web-related configuration or additional attributes such as requires-channel, so you will
not be able to access information on the current user or call secured methods during the request. Use
access='IS_AUTHENTICATED_ANONYMOUSLY' as an alternative if you still want the security filter
chain to be applied.
If you want to use basic authentication instead of form login, then change the configuration to
<http use-expressions="false">
<intercept-url pattern="/**" access="ROLE_USER" />
<http-basic />
</http>

Basic authentication will then take precedence and will be used to prompt for a login when a user
attempts to access a protected resource. Form login is still available in this configuration if you wish to
use it, for example through a login form embedded in another web page.
Setting a Default Post-Login Destination
If a form login isnt prompted by an attempt to access a protected resource, the default-targeturl option comes into play. This is the URL the user will be taken to after successfully logging in, and
defaults to "/". You can also configure things so that the user always ends up at this page (regardless
of whether the login was "on-demand" or they explicitly chose to log in) by setting the always-usedefault-target attribute to "true". This is useful if your application always requires that the user
starts at a "home" page, for example:
<http pattern="/login.htm*" security="none"/>
<http use-expressions="false">
<intercept-url pattern='/**' access='ROLE_USER' />
<form-login login-page='/login.htm' default-target-url='/home.htm'
always-use-default-target='true' />
</http>

For even more control over the destination, you can use the authentication-success-handlerref attribute as an alternative to default-target-url. The referenced bean should be an instance
of AuthenticationSuccessHandler. Youll find more on this in the Core Filters chapter and also in
the namespace appendix, as well as information on how to customize the flow when authentication fails.

Logout Handling
The logout element adds support for logging out by navigating to a particular URL. The default logout
URL is /logout, but you can set it to something else using the logout-url attribute. More information
on other available attributes may be found in the namespace appendix.

Using other Authentication Providers

In practice you will need a more scalable source of user information than a few names added to the
application context file. Most likely you will want to store your user information in something like a
6

The use of multiple <http> elements is an important feature, allowing the namespace to simultaneously support both stateful
and stateless paths within the same application, for example. The previous syntax, using the attribute filters="none" on an
intercept-url element is incompatible with this change and is no longer supported in 3.1.

4.0.2.RELEASE

Spring Security

Spring Security Reference

database or an LDAP server. LDAP namespace configuration is dealt with in the LDAP chapter, so we
wont cover it here. If you have a custom implementation of Spring Securitys UserDetailsService,
called "myUserDetailsService" in your application context, then you can authenticate against this using
<authentication-manager>
<authentication-provider user-service-ref='myUserDetailsService'/>
</authentication-manager>

If you want to use a database, then you can use

<authentication-manager>
<authentication-provider>
<jdbc-user-service data-source-ref="securityDataSource"/>
</authentication-provider>
</authentication-manager>

Where "securityDataSource" is the name of a DataSource bean in the application context, pointing at
a database containing the standard Spring Security user data tables. Alternatively, you could configure
a Spring Security JdbcDaoImpl bean and point at that using the user-service-ref attribute:
<authentication-manager>
<authentication-provider user-service-ref='myUserDetailsService'/>
</authentication-manager>
<beans:bean id="myUserDetailsService"
class="org.springframework.security.core.userdetails.jdbc.JdbcDaoImpl">
<beans:property name="dataSource" ref="dataSource"/>
</beans:bean>

You can also use standard AuthenticationProvider beans as follows

<authentication-manager>
<authentication-provider ref='myAuthenticationProvider'/>
</authentication-manager>

where myAuthenticationProvider is the name of a bean in your application context which

implements AuthenticationProvider. You can use multiple authentication-provider
elements, in which case the providers will be queried in the order they are declared. See Section 4.6,
The Authentication Manager and the Namespace for more on information on how the Spring Security
AuthenticationManager is configured using the namespace.
Adding a Password Encoder
Passwords should always be encoded using a secure hashing algorithm designed for the purpose (not
a standard algorithm like SHA or MD5). This is supported by the <password-encoder> element. With
bcrypt encoded passwords, the original authentication provider configuration would look like this:
<beans:bean name="bcryptEncoder"
class="org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder"/>
<authentication-manager>
<authentication-provider>
<password-encoder ref="bcryptEncoder"/>
<user-service>
<user name="jimi" password="d7e6351eaa13189a5a3641bab846c8e8c69ba39f"
authorities="ROLE_USER, ROLE_ADMIN" />
<user name="bob" password="4e7421b1b8765d8f9406d87e7cc6aa784c4ab97f"
authorities="ROLE_USER" />
</user-service>
</authentication-provider>
</authentication-manager>

4.0.2.RELEASE

Spring Security

Spring Security Reference

Bcrypt is a good choice for most cases, unless you have a legacy system which forces you to use
a different algorithm. If you are using a simple hashing algorithm or, even worse, storing plain text
passwords, then you should consider migrating to a more secure option like bcrypt.

4.3 Advanced Web Features

Remember-Me Authentication
See the separate Remember-Me chapter for information on remember-me namespace configuration.

Adding HTTP/HTTPS Channel Security

If your application supports both HTTP and HTTPS, and you require that particular URLs can only
be accessed over HTTPS, then this is directly supported using the requires-channel attribute on
<intercept-url>:
<http>
<intercept-url pattern="/secure/**" access="ROLE_USER" requires-channel="https"/>
<intercept-url pattern="/**" access="ROLE_USER" requires-channel="any"/>
...
</http>

With this configuration in place, if a user attempts to access anything matching the "/secure/**" pattern
7
using HTTP, they will first be redirected to an HTTPS URL . The available options are "http", "https" or
"any". Using the value "any" means that either HTTP or HTTPS can be used.
If your application uses non-standard ports for HTTP and/or HTTPS, you can specify a list of port
mappings as follows:
<http>
...
<port-mappings>
<port-mapping http="9080" https="9443"/>
</port-mappings>
</http>

Note that in order to be truly secure, an application should not use HTTP at all or switch between
HTTP and HTTPS. It should start in HTTPS (with the user entering an HTTPS URL) and use a secure
connection throughout to avoid any possibility of man-in-the-middle attacks.

Session Management
Detecting Timeouts
You can configure Spring Security to detect the submission of an invalid session ID and redirect the
user to an appropriate URL. This is achieved through the session-management element:
<http>
...
<session-management invalid-session-url="/invalidSession.htm" />
</http>

Note that if you use this mechanism to detect session timeouts, it may falsely report an error if the
user logs out and then logs back in without closing the browser. This is because the session cookie is
7

For more details on how channel-processing is implemented, see the Javadoc for ChannelProcessingFilter and related
classes.

4.0.2.RELEASE

Spring Security

Spring Security Reference

not cleared when you invalidate the session and will be resubmitted even if the user has logged out.
You may be able to explicitly delete the JSESSIONID cookie on logging out, for example by using the
following syntax in the logout handler:
<http>
<logout delete-cookies="JSESSIONID" />
</http>

Unfortunately this cant be guaranteed to work with every servlet container, so you will need to test it
in your environment
Note
If you are running your application behind a proxy, you may also be able to remove the session
cookie by configuring the proxy server. For example, using Apache HTTPDs mod_headers, the
following directive would delete the JSESSIONID cookie by expiring it in the response to a logout
request (assuming the application is deployed under the path /tutorial):
<LocationMatch "/tutorial/logout">
Header always set Set-Cookie "JSESSIONID=;Path=/tutorial;Expires=Thu, 01 Jan 1970 00:00:00 GMT"
</LocationMatch>

Concurrent Session Control

If you wish to place constraints on a single users ability to log in to your application, Spring Security
supports this out of the box with the following simple additions. First you need to add the following
listener to your web.xml file to keep Spring Security updated about session lifecycle events:
<listener>
<listener-class>
org.springframework.security.web.session.HttpSessionEventPublisher
</listener-class>
</listener>

Then add the following lines to your application context:

This will prevent a user from logging in multiple times - a second login will cause the first to be invalidated.
Often you would prefer to prevent a second login, in which case you can use
<http>
...
<session-management>
<concurrency-control max-sessions="1" error-if-maximum-exceeded="true" />
</session-management>
</http>

The second login will then be rejected. By "rejected", we mean that the user will be sent to the
authentication-failure-url if form-based login is being used. If the second authentication takes
place through another non-interactive mechanism, such as "remember-me", an "unauthorized" (401)
error will be sent to the client. If instead you want to use an error page, you can add the attribute
session-authentication-error-url to the session-management element.

4.0.2.RELEASE

Spring Security

Spring Security Reference

If you are using a customized authentication filter for form-based login, then you have to configure
concurrent session control support explicitly. More details can be found in the Session Management
chapter.
Session Fixation Attack Protection
Session fixation attacks are a potential risk where it is possible for a malicious attacker to create a
session by accessing a site, then persuade another user to log in with the same session (by sending
them a link containing the session identifier as a parameter, for example). Spring Security protects
against this automatically by creating a new session or otherwise changing the session ID when a user
logs in. If you dont require this protection, or it conflicts with some other requirement, you can control the
behavior using the session-fixation-protection attribute on <session-management>, which
has four options
none - Dont do anything. The original session will be retained.
newSession - Create a new "clean" session, without copying the existing session data (Spring
Security-related attributes will still be copied).
migrateSession - Create a new session and copy all existing session attributes to the new session.
This is the default in Servlet 3.0 or older containers.
changeSessionId - Do not create a new session. Instead, use the session fixation protection
provided by the Servlet container (HttpServletRequest#changeSessionId()). This option is
only available in Servlet 3.1 (Java EE 7) and newer containers. Specifying it in older containers will
result in an exception. This is the default in Servlet 3.1 and newer containers.
When session fixation protection occurs, it results in a SessionFixationProtectionEvent being
published in the application context. If you use changeSessionId, this protection will also result in
any javax.servlet.http.HttpSessionIdListener s being notified, so use caution if your code
listens for both events. See the Session Management chapter for additional information.

OpenID Support
The namespace supports OpenID login either instead of, or in addition to normal form-based login, with
a simple change:
<http>
<intercept-url pattern="/**" access="ROLE_USER" />
<openid-login />
</http>

You should then register yourself with an OpenID provider (such as myopenid.com), and add the user
information to your in-memory <user-service> :
<user name="http://jimi.hendrix.myopenid.com/" authorities="ROLE_USER" />

You should be able to login using the myopenid.com site to authenticate. It is also possible to select a
specific UserDetailsService bean for use OpenID by setting the user-service-ref attribute on
the openid-login element. See the previous section on authentication providers for more information.
Note that we have omitted the password attribute from the above user configuration, since this set of
user data is only being used to load the authorities for the user. A random password will be generate
internally, preventing you from accidentally using this user data as an authentication source elsewhere
in your configuration.

4.0.2.RELEASE

Spring Security

Spring Security Reference

Attribute Exchange
Support for OpenID attribute exchange. As an example, the following configuration would attempt to
retrieve the email and full name from the OpenID provider, for use by the application:
<openid-login>
<attribute-exchange>
<openid-attribute name="email" type="http://axschema.org/contact/email" required="true"/>
<openid-attribute name="name" type="http://axschema.org/namePerson"/>
</attribute-exchange>
</openid-login>

The "type" of each OpenID attribute is a URI, determined by a particular schema, in this case http://
axschema.org/. If an attribute must be retrieved for successful authentication, the required attribute
can be set. The exact schema and attributes supported will depend on your OpenID provider. The
attribute values are returned as part of the authentication process and can be accessed afterwards
using the following code:
OpenIDAuthenticationToken token =
(OpenIDAuthenticationToken)SecurityContextHolder.getContext().getAuthentication();
List<OpenIDAttribute> attributes = token.getAttributes();

The OpenIDAttribute contains the attribute type and the retrieved value (or values in the case
of multi-valued attributes). Well see more about how the SecurityContextHolder class is used
when we look at core Spring Security components in the technical overview chapter. Multiple attribute
exchange configurations are also be supported, if you wish to use multiple identity providers. You can
supply multiple attribute-exchange elements, using an identifier-matcher attribute on each.
This contains a regular expression which will be matched against the OpenID identifier supplied by
the user. See the OpenID sample application in the codebase for an example configuration, providing
different attribute lists for the Google, Yahoo and MyOpenID providers.

Response Headers
For additional information on how to customize the headers element refer to the Chapter 17, Security
HTTP Response Headers section of the reference.

Adding in Your Own Filters

If youve used Spring Security before, youll know that the framework maintains a chain of filters in
order to apply its services. You may want to add your own filters to the stack at particular locations
or use a Spring Security filter for which there isnt currently a namespace configuration option (CAS,
for example). Or you might want to use a customized version of a standard namespace filter, such as
the UsernamePasswordAuthenticationFilter which is created by the <form-login> element,
taking advantage of some of the extra configuration options which are available by using the bean
explicitly. How can you do this with namespace configuration, since the filter chain is not directly
exposed?
The order of the filters is always strictly enforced when using the namespace. When the application
context is being created, the filter beans are sorted by the namespace handling code and the standard
Spring Security filters each have an alias in the namespace and a well-known position.
Note
In previous versions, the sorting took place after the filter instances had been created, during
post-processing of the application context. In version 3.0+ the sorting is now done at the bean

4.0.2.RELEASE

Spring Security

Spring Security Reference

metadata level, before the classes have been instantiated. This has implications for how you add
your own filters to the stack as the entire filter list must be known during the parsing of the <http>
element, so the syntax has changed slightly in 3.0.
The filters, aliases and namespace elements/attributes which create the filters are shown in Table 4.1,
Standard Filter Aliases and Ordering. The filters are listed in the order in which they occur in the filter
chain.
Table 4.1. Standard Filter Aliases and Ordering
Alias

Filter Class

Namespace Element or
Attribute

CHANNEL_FILTER

ChannelProcessingFilter

http/intercepturl@requires-channel

SECURITY_CONTEXT_FILTER SecurityContextPersistenceFilter
http
CONCURRENT_SESSION_FILTER
ConcurrentSessionFilter

session-management/
concurrency-control

HEADERS_FILTER

HeaderWriterFilter

http/headers

CSRF_FILTER

CsrfFilter

http/csrf

LOGOUT_FILTER

LogoutFilter

http/logout

X509_FILTER

X509AuthenticationFilter http/x509

PRE_AUTH_FILTER

AbstractPreAuthenticatedProcessingFilter
N/A
Subclasses

CAS_FILTER

CasAuthenticationFilter

FORM_LOGIN_FILTER

UsernamePasswordAuthenticationFilter
http/form-login

BASIC_AUTH_FILTER

BasicAuthenticationFilterhttp/http-basic

N/A

SERVLET_API_SUPPORT_FILTER
SecurityContextHolderAwareRequestFilter
http/@servlet-apiprovision
JAAS_API_SUPPORT_FILTER JaasApiIntegrationFilter http/@jaas-apiprovision
REMEMBER_ME_FILTER

RememberMeAuthenticationFilter
http/remember-me

ANONYMOUS_FILTER

AnonymousAuthenticationFilter
http/anonymous

SESSION_MANAGEMENT_FILTER
SessionManagementFilter

session-management

EXCEPTION_TRANSLATION_FILTER
ExceptionTranslationFilter
http
FILTER_SECURITY_INTERCEPTOR
FilterSecurityInterceptorhttp
SWITCH_USER_FILTER

SwitchUserFilter

N/A

You can add your own filter to the stack, using the custom-filter element and one of these names
to specify the position your filter should appear at:

4.0.2.RELEASE

Spring Security

Spring Security Reference

You can also use the after or before attributes if you want your filter to be inserted before or after
another filter in the stack. The names "FIRST" and "LAST" can be used with the position attribute to
indicate that you want your filter to appear before or after the entire stack, respectively.
Avoiding filter position conflicts
If you are inserting a custom filter which may occupy the same position as one of the standard
filters created by the namespace then its important that you dont include the namespace versions
by mistake. Remove any elements which create filters whose functionality you want to replace.
Note that you cant replace filters which are created by the use of the <http>
element itself - SecurityContextPersistenceFilter, ExceptionTranslationFilter
or FilterSecurityInterceptor. Some other filters are added by default, but you can
disable them. An AnonymousAuthenticationFilter is added by default and unless you have
session-fixation protection disabled, a SessionManagementFilter will also be added to the
filter chain.
If youre replacing a namespace filter which requires an authentication entry point (i.e. where the
authentication process is triggered by an attempt by an unauthenticated user to access to a secured
resource), you will need to add a custom entry point bean too.
Setting a Custom AuthenticationEntryPoint
If you arent using form login, OpenID or basic authentication through the namespace, you may want
to define an authentication filter and entry point using a traditional bean syntax and link them into the
namespace, as weve just seen. The corresponding AuthenticationEntryPoint can be set using
the entry-point-ref attribute on the <http> element.
The CAS sample application is a good example of the use of custom beans with the namespace,
including this syntax. If you arent familiar with authentication entry points, they are discussed in the
technical overview chapter.

4.4 Method Security

From version 2.0 onwards Spring Security has improved support substantially for adding security to your
service layer methods. It provides support for JSR-250 annotation security as well as the frameworks
original @Secured annotation. From 3.0 you can also make use of new expression-based annotations.
You can apply security to a single bean, using the intercept-methods element to decorate the bean
declaration, or you can secure multiple beans across the entire service layer using the AspectJ style
pointcuts.

The <global-method-security> Element

This element is used to enable annotation-based security in your application (by setting the appropriate
attributes on the element), and also to group together security pointcut declarations which will be applied
across your entire application context. You should only declare one <global-method-security>
element. The following declaration would enable support for Spring Securitys @Secured:

4.0.2.RELEASE

Spring Security

Spring Security Reference

<global-method-security secured-annotations="enabled" />

Support for JSR-250 annotations can be enabled using

<global-method-security jsr250-annotations="enabled" />

These are standards-based and allow simple role-based constraints to be applied but do not have the
power Spring Securitys native annotations. To use the new expression-based syntax, you would use
<global-method-security pre-post-annotations="enabled" />

and the equivalent Java code would be

Expression-based annotations are a good choice if you need to define simple rules that go beyond
checking the role names against the users list of authorities.
Note
The annotated methods will only be secured for instances which are defined as Spring beans (in
the same application context in which method-security is enabled). If you want to secure instances
which are not created by Spring (using the new operator, for example) then you need to use
AspectJ.
Note
You can enable more than one type of annotation in the same application, but only one type
should be used for any interface or class as the behaviour will not be well-defined otherwise. If two
annotations are found which apply to a particular method, then only one of them will be applied.

4.0.2.RELEASE

Spring Security

Spring Security Reference

Adding Security Pointcuts using protect-pointcut

The use of protect-pointcut is particularly powerful, as it allows you to apply security to many
beans with only a simple declaration. Consider the following example:
<global-method-security>
<protect-pointcut expression="execution(* com.mycompany.*Service.*(..))"
access="ROLE_USER"/>
</global-method-security>

This will protect all methods on beans declared in the application context whose classes are in the
com.mycompany package and whose class names end in "Service". Only users with the ROLE_USER
role will be able to invoke these methods. As with URL matching, the most specific matches must come
first in the list of pointcuts, as the first matching expression will be used. Security annotations take
precedence over pointcuts.

4.5 The Default AccessDecisionManager

This section assumes you have some knowledge of the underlying architecture for access-control within
Spring Security. If you dont you can skip it and come back to it later, as this section is only really relevant
for people who need to do some customization in order to use more than simple role-based security.
When you use a namespace configuration, a default instance of AccessDecisionManager is
automatically registered for you and will be used for making access decisions for method invocations and
web URL access, based on the access attributes you specify in your intercept-url and protectpointcut declarations (and in annotations if you are using annotation secured methods).
The default strategy is to use an AffirmativeBased AccessDecisionManager with a RoleVoter
and an AuthenticatedVoter. You can find out more about these in the chapter on authorization.

Customizing the AccessDecisionManager

If you need to use a more complicated access control strategy then it is easy to set an alternative for
both method and web security.
For method security, you do this by setting the access-decision-manager-ref attribute on
global-method-security to the id of the appropriate AccessDecisionManager bean in the
application context:
<global-method-security access-decision-manager-ref="myAccessDecisionManagerBean">
...
</global-method-security>

The syntax for web security is the same, but on the http element:
<http access-decision-manager-ref="myAccessDecisionManagerBean">
...
</http>

4.6 The Authentication Manager and the Namespace

The main interface which provides authentication services in Spring Security is the
AuthenticationManager. This is usually an instance of Spring Securitys ProviderManager class,
which you may already be familiar with if youve used the framework before. If not, it will be covered
later, in the technical overview chapter. The bean instance is registered using the authentication-

4.0.2.RELEASE

Spring Security

Spring Security Reference

manager namespace element. You cant use a custom AuthenticationManager if you are using
either HTTP or method security through the namespace, but this should not be a problem as you have
full control over the AuthenticationProvider s that are used.
You may want to register additional AuthenticationProvider beans with the ProviderManager
and you can do this using the <authentication-provider> element with the ref attribute, where
the value of the attribute is the name of the provider bean you want to add. For example:
<authentication-manager>
<authentication-provider ref="casAuthenticationProvider"/>
</authentication-manager>
<bean id="casAuthenticationProvider"
class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
...
</bean>

Another common requirement is that another bean in the context may require a reference to the
AuthenticationManager. You can easily register an alias for the AuthenticationManager and
use this name elsewhere in your application context.
<security:authentication-manager alias="authenticationManager">
...
</security:authentication-manager>
<bean id="customizedFormLoginFilter"
class="com.somecompany.security.web.CustomFormLoginFilter">
<property name="authenticationManager" ref="authenticationManager"/>
...
</bean>

4.0.2.RELEASE

Spring Security

Spring Security Reference

5. Sample Applications
There are several sample web applications that are available with the project. To avoid an overly large
download, only the "tutorial" and "contacts" samples are included in the distribution zip file. The others
can be built directly from the source which you can obtain as described in the introduction. Its easy to
build the project yourself and theres more information on the project web site at http://spring.io/springsecurity/. All paths referred to in this chapter are relative to the project source directory.

5.1 Tutorial Sample

The tutorial sample is a nice basic example to get you started. It uses simple namespace configuration
throughout. The compiled application is included in the distribution zip file, ready to be deployed
into your web container (spring-security-samples-tutorial-3.1.x.war). The form-based
authentication mechanism is used in combination with the commonly-used remember-me authentication
provider to automatically remember the login using cookies.
We recommend you start with the tutorial sample, as the XML is minimal and easy to follow. Most
importantly, you can easily add this one XML file (and its corresponding web.xml entries) to your
existing application. Only when this basic integration is achieved do we suggest you attempt adding in
method authorization or domain object security.

5.2 Contacts
The Contacts Sample is an advanced example in that it illustrates the more powerful features of domain
object access control lists (ACLs) in addition to basic application security. The application provides an
interface with which the users are able to administer a simple database of contacts (the domain objects).
To deploy, simply copy the WAR file from Spring Security distribution into your containers webapps
directory. The war should be called spring-security-samples-contacts-3.1.x.war (the
appended version number will vary depending on what release you are using).
After starting your container, check the application can load. Visit http://localhost:8080/contacts (or
whichever URL is appropriate for your web container and the WAR you deployed).
Next, click "Debug". You will be prompted to authenticate, and a series of usernames and passwords
are suggested on that page. Simply authenticate with any of these and view the resulting page. It should
contain a success message similar to the following:

4.0.2.RELEASE

Spring Security

Spring Security Reference

Part III. Architecture

and Implementation
Once you are familiar with setting up and running some namespace-configuration based applications,
you may wish to develop more of an understanding of how the framework actually works behind the
namespace facade. Like most software, Spring Security has certain central interfaces, classes and
conceptual abstractions that are commonly used throughout the framework. In this part of the reference
guide we will look at some of these and see how they work together to support authentication and
access-control within Spring Security.

Spring Security Reference

7. Technical Overview
7.1 Runtime Environment
Spring Security 3.0 requires a Java 5.0 Runtime Environment or higher. As Spring Security aims to
operate in a self-contained manner, there is no need to place any special configuration files into your
Java Runtime Environment. In particular, there is no need to configure a special Java Authentication
and Authorization Service (JAAS) policy file or place Spring Security into common classpath locations.
Similarly, if you are using an EJB Container or Servlet Container there is no need to put any special
configuration files anywhere, nor include Spring Security in a server classloader. All the required files
will be contained within your application.
This design offers maximum deployment time flexibility, as you can simply copy your target artifact (be
it a JAR, WAR or EAR) from one system to another and it will immediately work.

7.2 Core Components

In Spring Security 3.0, the contents of the spring-security-core jar were stripped down to the
bare minimum. It no longer contains any code related to web-application security, LDAP or namespace
configuration. Well take a look here at some of the Java types that youll find in the core module. They
represent the building blocks of the the framework, so if you ever need to go beyond a simple namespace
configuration then its important that you understand what they are, even if you dont actually need to
interact with them directly.

SecurityContextHolder, SecurityContext and Authentication Objects

The most fundamental object is SecurityContextHolder. This is where we store details of the
present security context of the application, which includes details of the principal currently using the
application. By default the SecurityContextHolder uses a ThreadLocal to store these details,
which means that the security context is always available to methods in the same thread of execution,
even if the security context is not explicitly passed around as an argument to those methods. Using a
ThreadLocal in this way is quite safe if care is taken to clear the thread after the present principals
request is processed. Of course, Spring Security takes care of this for you automatically so there is no
need to worry about it.
Some applications arent entirely suitable for using a ThreadLocal, because of the specific way
they work with threads. For example, a Swing client might want all threads in a Java Virtual Machine
to use the same security context. SecurityContextHolder can be configured with a strategy on
startup to specify how you would like the context to be stored. For a standalone application you
would use the SecurityContextHolder.MODE_GLOBAL strategy. Other applications might want
to have threads spawned by the secure thread also assume the same security identity. This is
achieved by using SecurityContextHolder.MODE_INHERITABLETHREADLOCAL. You can change
the mode from the default SecurityContextHolder.MODE_THREADLOCAL in two ways. The first is
to set a system property, the second is to call a static method on SecurityContextHolder. Most
applications wont need to change from the default, but if you do, take a look at the JavaDocs for
SecurityContextHolder to learn more.
Obtaining information about the current user
Inside the SecurityContextHolder we store details of the principal currently interacting with the
application. Spring Security uses an Authentication object to represent this information. You wont

4.0.2.RELEASE

Spring Security

Spring Security Reference

normally need to create an Authentication object yourself, but it is fairly common for users to query
the Authentication object. You can use the following code block - from anywhere in your application
- to obtain the name of the currently authenticated user, for example:
Object principal = SecurityContextHolder.getContext().getAuthentication().getPrincipal();
if (principal instanceof UserDetails) {
String username = ((UserDetails)principal).getUsername();
} else {
String username = principal.toString();
}

The object returned by the call to getContext() is an instance of the SecurityContext interface.
This is the object that is kept in thread-local storage. As well see below, most authentication
mechanisms withing Spring Security return an instance of UserDetails as the principal.

The UserDetailsService
Another item to note from the above code fragment is that you can obtain a principal from the
Authentication object. The principal is just an Object. Most of the time this can be cast into a
UserDetails object. UserDetails is a core interface in Spring Security. It represents a principal,
but in an extensible and application-specific way. Think of UserDetails as the adapter between
your own user database and what Spring Security needs inside the SecurityContextHolder.
Being a representation of something from your own user database, quite often you will cast the
UserDetails to the original object that your application provided, so you can call business-specific
methods (like`getEmail(), `getEmployeeNumber() and so on).
By now youre probably wondering, so when do I provide a UserDetails object? How do I do that? I
thought you said this thing was declarative and I didnt need to write any Java code - what gives? The
short answer is that there is a special interface called UserDetailsService. The only method on this
interface accepts a String-based username argument and returns a UserDetails:
UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;

This is the most common approach to loading information for a user within Spring Security and you will
see it used throughout the framework whenever information on a user is required.
On successful authentication, UserDetails is used to build the Authentication object that is
stored in the SecurityContextHolder (more on this below). The good news is that we provide
a number of UserDetailsService implementations, including one that uses an in-memory map
(InMemoryDaoImpl) and another that uses JDBC (JdbcDaoImpl). Most users tend to write their
own, though, with their implementations often simply sitting on top of an existing Data Access Object
(DAO) that represents their employees, customers, or other users of the application. Remember
the advantage that whatever your UserDetailsService returns can always be obtained from the
SecurityContextHolder using the above code fragment.
Note
There is often some confusion about UserDetailsService. It is purely a DAO for user
data and performs no other function other than to supply that data to other components
within the framework. In particular, it does not authenticate the user, which is done
by the AuthenticationManager. In many cases it makes more sense to implement
AuthenticationProvider directly if you require a custom authentication process.

4.0.2.RELEASE

Spring Security

Spring Security Reference

GrantedAuthority
Besides the principal, another important method provided by Authentication is
getAuthorities(). This method provides an array of GrantedAuthority objects. A
GrantedAuthority is, not surprisingly, an authority that is granted to the principal. Such authorities
are usually "roles", such as ROLE_ADMINISTRATOR or ROLE_HR_SUPERVISOR. These roles are later
on configured for web authorization, method authorization and domain object authorization. Other
parts of Spring Security are capable of interpreting these authorities, and expect them to be present.
GrantedAuthority objects are usually loaded by the UserDetailsService.
Usually the GrantedAuthority objects are application-wide permissions. They are not specific to a
given domain object. Thus, you wouldnt likely have a GrantedAuthority to represent a permission
to Employee object number 54, because if there are thousands of such authorities you would quickly
run out of memory (or, at the very least, cause the application to take a long time to authenticate a user).
Of course, Spring Security is expressly designed to handle this common requirement, but youd instead
use the projects domain object security capabilities for this purpose.

Summary
Just to recap, the major building blocks of Spring Security that weve seen so far are:
SecurityContextHolder, to provide access to the SecurityContext.
SecurityContext, to hold the Authentication and possibly request-specific security
information.
Authentication, to represent the principal in a Spring Security-specific manner.
GrantedAuthority, to reflect the application-wide permissions granted to a principal.
UserDetails, to provide the necessary information to build an Authentication object from your
applications DAOs or other source of security data.
UserDetailsService, to create a UserDetails when passed in a String-based username (or
certificate ID or the like).
Now that youve gained an understanding of these repeatedly-used components, lets take a closer look
at the process of authentication.

7.3 Authentication
Spring Security can participate in many different authentication environments. While we recommend
people use Spring Security for authentication and not integrate with existing Container Managed
Authentication, it is nevertheless supported - as is integrating with your own proprietary authentication
system.

What is authentication in Spring Security?

Lets consider a standard authentication scenario that everyone is familiar with.
1. A user is prompted to log in with a username and password.
2. The system (successfully) verifies that the password is correct for the username.

4.0.2.RELEASE

Spring Security

Spring Security Reference

3. The context information for that user is obtained (their list of roles and so on).
4. A security context is established for the user
5. The user proceeds, potentially to perform some operation which is potentially protected by an access
control mechanism which checks the required permissions for the operation against the current
security context information.
The first three items constitute the authentication process so well take a look at how these take place
within Spring Security.
1. The username and password are obtained and combined into an instance of
UsernamePasswordAuthenticationToken (an instance of the Authentication interface,
which we saw earlier).
2. The token is passed to an instance of AuthenticationManager for validation.
3. The AuthenticationManager returns a fully populated Authentication instance on successful
authentication.
4. The
security
context
is
established
by
calling
SecurityContextHolder.getContext().setAuthentication(), passing in the returned
authentication object.
From that point on, the user is considered to be authenticated. Lets look at some code as an example.

4.0.2.RELEASE

Spring Security

Spring Security Reference

import
import
import
import

org.springframework.security.authentication.*;
org.springframework.security.core.*;
org.springframework.security.core.authority.SimpleGrantedAuthority;
org.springframework.security.core.context.SecurityContextHolder;

public class AuthenticationExample {

private static AuthenticationManager am = new SampleAuthenticationManager();
public static void main(String[] args) throws Exception {
BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
while(true) {
System.out.println("Please enter your username:");
String name = in.readLine();
System.out.println("Please enter your password:");
String password = in.readLine();
try {
Authentication request = new UsernamePasswordAuthenticationToken(name, password);
Authentication result = am.authenticate(request);
SecurityContextHolder.getContext().setAuthentication(result);
break;
} catch(AuthenticationException e) {
System.out.println("Authentication failed: " + e.getMessage());
}
}
System.out.println("Successfully authenticated. Security context contains: " +
SecurityContextHolder.getContext().getAuthentication());
}
}
class SampleAuthenticationManager implements AuthenticationManager {
static final List<GrantedAuthority> AUTHORITIES = new ArrayList<GrantedAuthority>();
static {
AUTHORITIES.add(new SimpleGrantedAuthority("ROLE_USER"));
}
public Authentication authenticate(Authentication auth) throws AuthenticationException {
if (auth.getName().equals(auth.getCredentials())) {
return new UsernamePasswordAuthenticationToken(auth.getName(),
auth.getCredentials(), AUTHORITIES);
}
throw new BadCredentialsException("Bad Credentials");
}
}

Here we have written a little program that asks the user to enter a username and password and performs
the above sequence. The AuthenticationManager which weve implemented here will authenticate
any user whose username and password are the same. It assigns a single role to every user. The output
from the above will be something like:
Please enter your username:
bob
Please enter your password:
password
Authentication failed: Bad Credentials
Please enter your username:
bob
Please enter your password:
bob
Successfully authenticated. Security context contains: \
org.springframework.security.authentication.UsernamePasswordAuthenticationToken@441d0230: \
Principal: bob; Password: [PROTECTED]; \
Authenticated: true; Details: null; \
Granted Authorities: ROLE_USER

Note that you dont normally need to write any code like this. The process will normally occur internally,
in a web authentication filter for example. Weve just included the code here to show that the question

4.0.2.RELEASE

Spring Security

Spring Security Reference

of what actually constitutes authentication in Spring Security has quite a simple answer. A user is
authenticated when the SecurityContextHolder contains a fully populated Authentication
object.

Setting the SecurityContextHolder Contents Directly

In fact, Spring Security doesnt mind how you
inside the SecurityContextHolder. The only
SecurityContextHolder contains an Authentication
AbstractSecurityInterceptor (which well see more
operation.

put the Authentication object

critical requirement is that the
which represents a principal before the
about later) needs to authorize a user

You can (and many users do) write their own filters or MVC controllers to provide interoperability
with authentication systems that are not based on Spring Security. For example, you might be using
Container-Managed Authentication which makes the current user available from a ThreadLocal or JNDI
location. Or you might work for a company that has a legacy proprietary authentication system, which
is a corporate "standard" over which you have little control. In situations like this its quite easy to
get Spring Security to work, and still provide authorization capabilities. All you need to do is write a
filter (or equivalent) that reads the third-party user information from a location, build a Spring Securityspecific Authentication object, and put it into the SecurityContextHolder. In this case you also
need to think about things which are normally taken care of automatically by the built-in authentication
infrastructure. For example, you might need to pre-emptively create an HTTP session to cache the
context between requests, before you write the response to the client footnote:[It isnt possible to create
a session once the response has been committed.
If youre wondering how the AuthenticationManager is implemented in a real world example, well
look at that in the core services chapter.

7.4 Authentication in a Web Application

Now lets explore the situation where you are using Spring Security in a web application (without
web.xml security enabled). How is a user authenticated and the security context established?
Consider a typical web applications authentication process:
1. You visit the home page, and click on a link.
2. A request goes to the server, and the server decides that youve asked for a protected resource.
3. As youre not presently authenticated, the server sends back a response indicating that you must
authenticate. The response will either be an HTTP response code, or a redirect to a particular web
page.
4. Depending on the authentication mechanism, your browser will either redirect to the specific web
page so that you can fill out the form, or the browser will somehow retrieve your identity (via a BASIC
authentication dialogue box, a cookie, a X.509 certificate etc.).
5. The browser will send back a response to the server. This will either be an HTTP POST containing
the contents of the form that you filled out, or an HTTP header containing your authentication details.
6. Next the server will decide whether or not the presented credentials are valid. If theyre valid, the
next step will happen. If theyre invalid, usually your browser will be asked to try again (so you return
to step two above).

4.0.2.RELEASE

Spring Security

Spring Security Reference

7. The original request that you made to cause the authentication process will be retried. Hopefully
youve authenticated with sufficient granted authorities to access the protected resource. If you have
sufficient access, the request will be successful. Otherwise, youll receive back an HTTP error code
403, which means "forbidden".
Spring Security has distinct classes responsible for most of the steps described above. The
main participants (in the order that they are used) are the ExceptionTranslationFilter, an
AuthenticationEntryPoint and an "authentication mechanism", which is responsible for calling
the AuthenticationManager which we saw in the previous section.

ExceptionTranslationFilter
ExceptionTranslationFilter is a Spring Security filter that has responsibility for detecting
any Spring Security exceptions that are thrown. Such exceptions will generally be thrown by an
AbstractSecurityInterceptor, which is the main provider of authorization services. We will
discuss AbstractSecurityInterceptor in the next section, but for now we just need to know that it
produces Java exceptions and knows nothing about HTTP or how to go about authenticating a principal.
Instead the ExceptionTranslationFilter offers this service, with specific responsibility for either
returning error code 403 (if the principal has been authenticated and therefore simply lacks sufficient
access - as per step seven above), or launching an AuthenticationEntryPoint (if the principal
has not been authenticated and therefore we need to go commence step three).

AuthenticationEntryPoint
The AuthenticationEntryPoint is responsible for step three in the above list. As you can imagine,
each web application will have a default authentication strategy (well, this can be configured like nearly
everything else in Spring Security, but lets keep it simple for now). Each major authentication system
will have its own AuthenticationEntryPoint implementation, which typically performs one of the
actions described in step 3.

Authentication Mechanism
Once your browser submits your authentication credentials (either as an HTTP form post or HTTP
header) there needs to be something on the server that"collects" these authentication details. By now
were at step six in the above list. In Spring Security we have a special name for the function of collecting
authentication details from a user agent (usually a web browser), referring to it as the "authentication
mechanism". Examples are form-base login and Basic authentication. Once the authentication details
have been collected from the user agent, an Authentication`"request" object is built
and then presented to the `AuthenticationManager.
After the authentication mechanism receives back the fully-populated Authentication object, it will
deem the request valid, put the Authentication into the SecurityContextHolder, and cause the
original request to be retried (step seven above). If, on the other hand, the AuthenticationManager
rejected the request, the authentication mechanism will ask the user agent to retry (step two above).

Storing the SecurityContext between requests

Depending on the type of application, there may need to be a strategy in place to store the security
context between user operations. In a typical web application, a user logs in once and is subsequently
identified by their session Id. The server caches the principal information for the duration session. In
Spring Security, the responsibility for storing the SecurityContext between requests falls to the
SecurityContextPersistenceFilter, which by default stores the context as an HttpSession
attribute between HTTP requests. It restores the context to the SecurityContextHolder for each

4.0.2.RELEASE

Spring Security

Spring Security Reference

request and, crucially, clears the SecurityContextHolder when the request completes. You
shouldnt interact directly with the HttpSession for security purposes. There is simply no justification
for doing so - always use the SecurityContextHolder instead.
Many other types of application (for example, a stateless RESTful web service) do not use
HTTP sessions and will re-authenticate on every request. However, it is still important that
the SecurityContextPersistenceFilter is included in the chain to make sure that the
SecurityContextHolder is cleared after each request.
Note
In an application which receives concurrent requests in a single session, the same
SecurityContext instance will be shared between threads. Even though a ThreadLocal
is being used, it is the same instance that is retrieved from the HttpSession for
each thread. This has implications if you wish to temporarily change the context under
which a thread is running. If you just use SecurityContextHolder.getContext(),
and call setAuthentication(anAuthentication) on the returned context object,
then the Authentication object will change in all concurrent threads which
share the same SecurityContext instance. You can customize the behaviour of
SecurityContextPersistenceFilter to create a completely new SecurityContext for
each request, preventing changes in one thread from affecting another. Alternatively you can
create a new instance just at the point where you temporarily change the context. The method
SecurityContextHolder.createEmptyContext() always returns a new context instance.

7.5 Access-Control (Authorization) in Spring Security

The main interface responsible for making access-control decisions in Spring Security is the
AccessDecisionManager. It has a decide method which takes an Authentication object
representing the principal requesting access, a "secure object" (see below) and a list of security
metadata attributes which apply for the object (such as a list of roles which are required for access to
be granted).

Security and AOP Advice

Only developers contemplating an entirely new way of intercepting and authorizing requests would need
to use secure objects directly. For example, it would be possible to build a new secure object to secure
calls to a messaging system. Anything that requires security and also provides a way of intercepting
a call (like the AOP around advice semantics) is capable of being made into a secure object. Having
said that, most Spring applications will simply use the three currently supported secure object types
(AOP Alliance MethodInvocation, AspectJ JoinPoint and web request FilterInvocation) with
complete transparency.

7.6 Localization
Spring Security supports localization of exception messages that end users are likely to see. If your
application is designed for English-speaking users, you dont need to do anything as by default all
Security Security messages are in English. If you need to support other locales, everything you need
to know is contained in this section.
All exception messages can be localized, including messages related to authentication failures and
access being denied (authorization failures). Exceptions and logging messages that are focused on
developers or system deployers (including incorrect attributes, interface contract violations, using
incorrect constructors, startup time validation, debug-level logging) are not localized and instead are
hard-coded in English within Spring Securitys code.
Shipping
in
the
spring-security-core-xx.jar
you
will
find
an
org.springframework.security package that in turn contains a messages.properties
file, as well as localized versions for some common languages. This should be referred to by
your`ApplicationContext`, as Spring Security classes implement Springs MessageSourceAware
interface and expect the message resolver to be dependency injected at application context startup time.
Usually all you need to do is register a bean inside your application context to refer to the messages.
An example is shown below:
<bean id="messageSource"
class="org.springframework.context.support.ReloadableResourceBundleMessageSource">
<property name="basename" value="classpath:org/springframework/security/messages"/>
</bean>

The messages.properties is named in accordance with standard resource bundles and represents
the default language supported by Spring Security messages. This default file is in English.
If you wish to customize the messages.properties file, or support other languages, you should copy
the file, rename it accordingly, and register it inside the above bean definition. There are not a large
number of message keys inside this file, so localization should not be considered a major initiative. If
you do perform localization of this file, please consider sharing your work with the community by logging
a JIRA task and attaching your appropriately-named localized version of messages.properties.
Spring Security relies on Springs localization support in order to actually lookup the appropriate
message. In order for this to work, you have to make sure that the locale from the incoming
request is stored in Springs org.springframework.context.i18n.LocaleContextHolder.
Spring MVCs DispatcherServlet does this for your application automatically, but since Spring
Securitys filters are invoked before this, the LocaleContextHolder needs to be set up to contain
the correct Locale before the filters are called. You can either do this in a filter yourself (which must
come before the Spring Security filters in`web.xml`) or you can use Springs RequestContextFilter.
Please refer to the Spring Framework documentation for further details on using localization with Spring.

4.0.2.RELEASE

Spring Security

Spring Security Reference

The "contacts" sample application is set up to use localized messages.

4.0.2.RELEASE

Spring Security

Spring Security Reference

8. Core Services
Now that we have a high-level overview of the Spring Security architecture and its core classes,
lets take a closer look at one or two of the core interfaces and their implementations, in particular
the AuthenticationManager, UserDetailsService and the AccessDecisionManager. These
crop up regularly throughout the remainder of this document so its important you know how they are
configured and how they operate.

8.1 The AuthenticationManager, ProviderManager and

AuthenticationProvider
The AuthenticationManager is just an interface, so the implementation can be anything we choose,
but how does it work in practice? What if we need to check multiple authentication databases or a
combination of different authentication services such as a database and an LDAP server?
The default implementation in Spring Security is called ProviderManager and rather than handling
the authentication request itself, it delegates to a list of configured AuthenticationProvider s,
each of which is queried in turn to see if it can perform the authentication. Each provider will either
throw an exception or return a fully populated Authentication object. Remember our good friends,
UserDetails and UserDetailsService? If not, head back to the previous chapter and refresh your
memory. The most common approach to verifying an authentication request is to load the corresponding
UserDetails and check the loaded password against the one that has been entered by the user. This
is the approach used by the DaoAuthenticationProvider (see below). The loaded UserDetails
object - and particularly the GrantedAuthority s it contains - will be used when building the fully
populated Authentication object which is returned from a successful authentication and stored in
the SecurityContext.
If you are using the namespace, an instance of ProviderManager is created and maintained internally,
and you add providers to it by using the namespace authentication provider elements (see the
namespace chapter). In this case, you should not declare a ProviderManager bean in your application
context. However, if you are not using the namespace then you would declare it like so:
<bean id="authenticationManager"
class="org.springframework.security.authentication.ProviderManager">
<constructor-arg>
<list>
<ref local="daoAuthenticationProvider"/>
<ref local="anonymousAuthenticationProvider"/>
<ref local="ldapAuthenticationProvider"/>
</list>
</constructor-arg>
</bean>

In the above example we have three providers. They are tried in the order shown (which is implied
by the use of a List), with each provider able to attempt authentication, or skip authentication
by simply returning null. If all implementations return null, the ProviderManager will throw a
ProviderNotFoundException. If youre interested in learning more about chaining providers, please
refer to the ProviderManager JavaDocs.
Authentication mechanisms such as a web form-login processing filter are injected with a reference
to the ProviderManager and will call it to handle their authentication requests. The providers you
require will sometimes be interchangeable with the authentication mechanisms, while at other times they
will depend on a specific authentication mechanism. For example, DaoAuthenticationProvider
and LdapAuthenticationProvider are compatible with any mechanism which submits a simple

4.0.2.RELEASE

Spring Security

Spring Security Reference

username/password authentication request and so will work with form-based logins or HTTP Basic
authentication. On the other hand, some authentication mechanisms create an authentication
request object which can only be interpreted by a single type of AuthenticationProvider.
An example of this would be JA-SIG CAS, which uses the notion of a service ticket and so
can therefore only be authenticated by a CasAuthenticationProvider. You neednt be too
concerned about this, because if you forget to register a suitable provider, youll simply receive a
ProviderNotFoundException when an attempt to authenticate is made.

Erasing Credentials on Successful Authentication

By default (from Spring Security 3.1 onwards) the ProviderManager will attempt to clear any
sensitive credentials information from the Authentication object which is returned by a successful
authentication request. This prevents information like passwords being retained longer than necessary.
This may cause issues when you are using a cache of user objects, for example, to improve performance
in a stateless application. If the Authentication contains a reference to an object in the cache (such
as a UserDetails instance) and this has its credentials removed, then it will no longer be possible
to authenticate against the cached value. You need to take this into account if you are using a cache.
An obvious solution is to make a copy of the object first, either in the cache implementation or in the
AuthenticationProvider which creates the returned Authentication object. Alternatively, you
can disable the eraseCredentialsAfterAuthentication property on ProviderManager. See
the Javadoc for more information.

DaoAuthenticationProvider
The
simplest
AuthenticationProvider
implemented
by
Spring
Security
is
DaoAuthenticationProvider, which is also one of the earliest supported by the framework. It
leverages a UserDetailsService (as a DAO) in order to lookup the username, password and
GrantedAuthority s. It authenticates the user simply by comparing the password submitted in a
UsernamePasswordAuthenticationToken against the one loaded by the UserDetailsService.
Configuring the provider is quite simple:
<bean id="daoAuthenticationProvider"
class="org.springframework.security.authentication.dao.DaoAuthenticationProvider">
<property name="userDetailsService" ref="inMemoryDaoImpl"/>
<property name="passwordEncoder" ref="passwordEncoder"/>
</bean>

The PasswordEncoder is optional. A PasswordEncoder provides encoding and decoding

of passwords presented in the UserDetails object that is returned from the configured
UserDetailsService. This will be discussed in more detail below.

8.2 UserDetailsService Implementations

As mentioned in the earlier in this reference guide, most authentication providers take advantage
of the UserDetails and UserDetailsService interfaces. Recall that the contract for
UserDetailsService is a single method:
UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;

The returned UserDetails is an interface that provides getters that guarantee non-null provision of
authentication information such as the username, password, granted authorities and whether the user
account is enabled or disabled. Most authentication providers will use a`UserDetailsService`, even if
the username and password are not actually used as part of the authentication decision. They may use

4.0.2.RELEASE

Spring Security

Spring Security Reference

the returned UserDetails object just for its GrantedAuthority information, because some other
system (like LDAP or X.509 or CAS etc) has undertaken the responsibility of actually validating the
credentials.
Given UserDetailsService is so simple to implement, it should be easy for users to retrieve
authentication information using a persistence strategy of their choice. Having said that, Spring Security
does include a couple of useful base implementations, which well look at below.

In-Memory Authentication
Is easy to use create a custom UserDetailsService implementation that extracts information from a
persistence engine of choice, but many applications do not require such complexity. This is particularly
true if youre building a prototype application or just starting integrating Spring Security, when you dont
really want to spend time configuring databases or writing UserDetailsService implementations.
For this sort of situation, a simple option is to use the user-service element from the security
namespace:
<user-service id="userDetailsService">
<user name="jimi" password="jimispassword" authorities="ROLE_USER, ROLE_ADMIN" />
<user name="bob" password="bobspassword" authorities="ROLE_USER" />
</user-service>

This also supports the use of an external properties file:

<user-service id="userDetailsService" properties="users.properties"/>

The properties file should contain entries in the form

username=password,grantedAuthority[,grantedAuthority][,enabled|disabled]

For example
jimi=jimispassword,ROLE_USER,ROLE_ADMIN,enabled
bob=bobspassword,ROLE_USER,enabled

JdbcDaoImpl
Spring Security also includes a UserDetailsService that can obtain authentication information from
a JDBC data source. Internally Spring JDBC is used, so it avoids the complexity of a fully-featured object
relational mapper (ORM) just to store user details. If your application does use an ORM tool, you might
prefer to write a custom UserDetailsService to reuse the mapping files youve probably already
created. Returning to JdbcDaoImpl, an example configuration is shown below:
<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
<property name="driverClassName" value="org.hsqldb.jdbcDriver"/>
<property name="url" value="jdbc:hsqldb:hsql://localhost:9001"/>
<property name="username" value="sa"/>
<property name="password" value=""/>
</bean>
<bean id="userDetailsService"
class="org.springframework.security.core.userdetails.jdbc.JdbcDaoImpl">
<property name="dataSource" ref="dataSource"/>
</bean>

You can use different relational database management systems by modifying the
DriverManagerDataSource shown above. You can also use a global data source obtained from
JNDI, as with any other Spring configuration.

4.0.2.RELEASE

Spring Security

Spring Security Reference

Authority Groups
By default, JdbcDaoImpl loads the authorities for a single user with the assumption that the authorities
are mapped directly to users (see the database schema appendix). An alternative approach is to partition
the authorities into groups and assign groups to the user. Some people prefer this approach as a means
of administering user rights. See the JdbcDaoImpl Javadoc for more information on how to enable the
use of group authorities. The group schema is also included in the appendix.

8.3 Password Encoding

Spring Securitys PasswordEncoder interface is used to support the use of passwords which
are encoded in some way in persistent storage. You should never store passwords in plain text.
Always use a one-way password hashing algorithm such as bcrypt which uses a built-in salt
value which is different for each stored password. Do not use a plain hash function such as
MD5 or SHA, or even a salted version. Bcrypt is deliberately designed to be slow and to hinder
offline password cracking, whereas standard hash algorithms are fast and can easily be used
to test thousands of passwords in parallel on custom hardware. You might think this doesnt
apply to you since your password database is secure and offline attacks arent a risk. If so, do
some research and read up on all the high-profile sites which have been compromised in this
way and have been pilloried for storing their passwords insecurely. Its best to be on the safe
side. Using org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder" is
a good choice for security. There are also compatible implementations in other common programming
languages so it a good choice for interoperability too.
If you are using a legacy system which already has hashed passwords, then you will need to
use an encoder which matches your current algorithm, at least until you can migrate your users
to a more secure scheme (usually this will involve asking the user to set a new password, since
hashes are irreversible). Spring Security has a package containing legacy password encoding
implementation, namely, org.springframework.security.authentication.encoding. The
DaoAuthenticationProvider can be injected with either the new or legacy PasswordEncoder
types.

What is a hash?
Password hashing is not unique to Spring Security but is a common source of confusion for users who
are not familiar with the concept. A hash (or digest) algorithm is a one-way function which produces a
piece of fixed-length output data (the hash) from some input data, such as a password. As an example,
the MD5 hash of the string "password" (in hexadecimal) is
5f4dcc3b5aa765d61d8327deb882cf99

A hash is "one-way" in the sense that it is very difficult (effectively impossible) to obtain the original
input given the hash value, or indeed any possible input which would produce that hash value. This
property makes hash values very useful for authentication purposes. They can be stored in your user
database as an alternative to plaintext passwords and even if the values are compromised they do not
immediately reveal a password which can be used to login. Note that this also means you have no way
of recovering the password once it is encoded.

Adding Salt to a Hash

One potential problem with the use of password hashes that it is relatively easy to get round the one-way
property of the hash if a common word is used for the input. People tend to choose similar passwords

4.0.2.RELEASE

Spring Security

Spring Security Reference

and huge dictionaries of these from previously hacked sites are available online. For example, if you
search for the hash value 5f4dcc3b5aa765d61d8327deb882cf99 using google, you will quickly
find the original word "password". In a similar way, an attacker can build a dictionary of hashes from
a standard word list and use this to lookup the original password. One way to help prevent this is to
have a suitably strong password policy to try to prevent common words from being used. Another is to
use a"salt" when calculating the hashes. This is an additional string of known data for each user which
is combined with the password before calculating the hash. Ideally the data should be as random as
possible, but in practice any salt value is usually preferable to none. Using a salt means that an attacker
has to build a separate dictionary of hashes for each salt value, making the attack more complicated
(but not impossible).
Bcrypt automatically generates a random salt value for each password when it is encoded, and stores
it in the bcrypt string in a standard format.
Note
The legacy approach to handling salt was to inject a SaltSource into the
DaoAuthenticationProvider, which would obtain a salt value for a particular user and pass
it to the PasswordEncoder. Using bcrypt means you dont have worry about the details of salt
handling (such as where the the value is stored), as it is all done internally. So wed strongly
recommend you use bcrypt unless you already have a system in place which stores the salt
separately.

Hashing and Authentication

When an authentication provider (such as Spring Securitys DaoAuthenticationProvider) needs
to check the password in a submitted authentication request against the known value for a user, and
the stored password is encoded in some way, then the submitted value must be encoded using exactly
the same algorithm. Its up to you to check that these are compatible as Spring Security has no control
over the persistent values. If you add password hashing to your authentication configuration in Spring
Security, and your database contains plaintext passwords, then there is no way authentication can
succeed. Even if you are aware that your database is using MD5 to encode the passwords, for example,
and your application is configured to use Spring Securitys Md5PasswordEncoder, there are still things
that can go wrong. The database may have the passwords encoded in Base 64, for example while the
encoder is using hexadecimal strings (the default). Alternatively your database may be using upper-case
while the output from the encoder is lower-case. Make sure you write a test to check the output from your
configured password encoder with a known password and salt combination and check that it matches
the database value before going further and attempting to authenticate through your application. Using
a standard like bcrypt will avoid these issues.
If you want to generate encoded passwords directly in Java for storage in your user database, then you
can use the encode method on the PasswordEncoder.

4.0.2.RELEASE

Spring Security

Part IV. Testing

Spring Security Reference

9. Testing Method Security

This section demonstrates how to use Spring Securitys Test support to test method based security. We
first introduce a MessageService that requires the user to be authenticated in order to access it.
public class HelloMessageService implements MessageService {
@PreAuthorize("authenticated")
public String getMessage() {
Authentication authentication = SecurityContextHolder.getContext()
.getAuthentication();
return "Hello " + authentication;
}
}

The result of getMessage is a String saying "Hello" to the current Spring Security Authentication.
An example of the output is displayed below.
Hello org.springframework.security.authentication.UsernamePasswordAuthenticationToken@ca25360:
Principal: org.springframework.security.core.userdetails.User@36ebcb: Username: user; Password:
[PROTECTED]; Enabled: true; AccountNonExpired: true; credentialsNonExpired: true; AccountNonLocked:
true; Granted Authorities: ROLE_USER; Credentials: [PROTECTED]; Authenticated: true; Details: null;
Granted Authorities: ROLE_USER

9.1 Security Test Setup

Before we can use Spring Security Test support, we must perform some setup. An example can be
seen below:
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
public class WithMockUserTests {

This is a basic example of how to setup Spring Security Test. The highlights are:

@RunWith instructs the spring-test module that it should create an ApplicationContext This is no
different than using the existing Spring Test support. For additional information, refer to the Spring
Reference
@ContextConfiguration instructs the spring-test the configuration to use to create the
ApplicationContext. Since no configuration is specified, the default configuration locations will
be tried. This is no different than using the existing Spring Test support. For additional information,
refer to the Spring Reference

Note
Spring
Security
hooks
into
Spring
Test
support
using
the
WithSecurityContextTestExecutionListener which will ensure our tests are ran with
the correct user. It does this by populating the SecurityContextHolder prior to running
our tests. After the test is done, it will clear out the SecurityContextHolder. If you
only need Spring Security related support, you can replace @ContextConfiguration with
@SecurityExecutionListeners.
Remember we added the @PreAuthorize annotation to our HelloMessageService and so it
requires an authenticated user to invoke it. If we ran the following test, we would expect the following
test will pass:

4.0.2.RELEASE

Spring Security

Spring Security Reference

@Test(expected = AuthenticationCredentialsNotFoundException.class)
public void getMessageUnauthenticated() {
messageService.getMessage();
}

9.2 @WithMockUser
The question is "How could we most easily run the test as a specific user?" The answer is to use
@WithMockUser. The following test will be ran as a user with the username "user", the password
"password", and the roles "ROLE_USER".
@Test
@WithMockUser
public void getMessageWithMockUser() {
String message = messageService.getMessage();
...
}

Specifically the following is true:

The user with the username "user" does not have to exist since we are mocking the user
The Authentication that is populated
UsernamePasswordAuthenticationToken

the

SecurityContext

Spring Security provides comprehensive integration with Spring MVC Test

10.1 Setting Up MockMvc and Spring Security

In order to use Spring Security with Spring MVC Test it is necessary to add the
Spring Security FilterChainProxy as a Filter. It is also necessary to add Spring
Securitys TestSecurityContextHolderPostProcessor to support Running as a User
in Spring MVC Test with Annotations. This can be done using Spring Securitys
SecurityMockMvcConfigurers.springSecurity(). For example:
Note
Spring Securitys testing support requires spring-test-4.1.3.RELEASE or greater.
import static org.springframework.security.test.web.servlet.setup.SecurityMockMvcConfigurers.*;
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
@WebAppConfiguration
public class CsrfShowcaseTests {
@Autowired
private WebApplicationContext context;
private MockMvc mvc;
@Before
public void setup() {
mvc = MockMvcBuilders
.webAppContextSetup(context)
.apply(springSecurity())
.build();
}
...

SecurityMockMvcConfigurers.springSecurity() will perform all of the initial setup we

need to integrate Spring Security with Spring MVC Test

10.2 SecurityMockMvcRequestPostProcessors
Spring MVC Test provides a convenient interface called a RequestPostProcessor that can be used
to modify a request. Spring Security provides a number of RequestPostProcessor implementations
that make testing easier. In order to use Spring Securitys RequestPostProcessor implementations
ensure the following static import is used:
import static
org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.*;

Testing with CSRF Protection

When testing any non safe HTTP methods and using Spring Securitys CSRF protection, you must
be sure to include a valid CSRF Token in the request. To specify a valid CSRF token as a request
parameter using the following:

4.0.2.RELEASE

Spring Security

Spring Security Reference

mvc
.perform(post("/").with(csrf()))

If you like you can include CSRF token in the header instead:
mvc
.perform(post("/").with(csrf().asHeader()))

You can also test providing an invalid CSRF token using the following:
mvc
.perform(post("/").with(csrf().useInvalidToken()))

Running a Test as a User in Spring MVC Test

It is often desirable to run tests as a specific user. There are two simple ways of populating the user:
Running as a User in Spring MVC Test with RequestPostProcessor
Running as a User in Spring MVC Test with Annotations

Running as a User in Spring MVC Test with RequestPostProcessor

There are a number of options available to populate a test user. For example, the following will run as
a user (which does not need to exist) with the username "user", the password "password", and the role
"ROLE_USER":
mvc
.perform(get("/").with(user("user")))

You can easily make customizations. For example, the following will run as a user (which does not
need to exist) with the username "admin", the password "pass", and the roles "ROLE_USER" and
"ROLE_ADMIN".
mvc
.perform(get("/admin").with(user("admin").password("pass").roles("USER","ADMIN")))

If you have a custom UserDetails that you would like to use, you can easily specify that as well. For
example, the following will use the specified UserDetails (which does not need to exist) to run with
a UsernamePasswordAuthenticationToken that has a principal of the specified UserDetails:
mvc
.perform(get("/").with(user(userDetails)))

If you want a custom Authentication (which does not need to exist) you can do so using the following:
mvc
.perform(get("/").with(authentication(authentication)))

You can even customize the SecurityContext using the following:

mvc
.perform(get("/").with(securityContext(securityContext)))

We can also ensure to run as a specific user for every request by using `MockMvcBuilderss default
request. For example, the following will run as a user (which does not need to exist) with the username
"admin", the password "password", and the role "ROLE_ADMIN":

4.0.2.RELEASE

Spring Security

Spring Security Reference

mvc = MockMvcBuilders
.webAppContextSetup(context)
.defaultRequest(get("/").with(user("user").roles("ADMIN")))
.apply(springSecurity())
.build();

If you find you are using the same user in many of your tests, it is recommended to move
the user to a method. For example, you can specify the following in your own class named
CustomSecurityMockMvcRequestPostProcessors:
public static RequestPostProcessor rob() {
return user("rob").roles("ADMIN");
}

Now you can perform a static import on SecurityMockMvcRequestPostProcessors and use that
within your tests:
import static sample.CustomSecurityMockMvcRequestPostProcessors.*;
...
mvc
.perform(get("/").with(rob()))

Running as a User in Spring MVC Test with Annotations

As an alternative to using a RequestPostProcessor to create your user, you can use annotations
described in Chapter 9, Testing Method Security. For example, the following will run the test with the
user with username "user", password "password", and role "ROLE_USER":
@Test
@WithMockUser
public void requestProtectedUrlWithUser() throws Exception {
mvc
.perform(get("/"))
...
}

Alternatively, the following will run the test with the user with username "user", password "password",
and role "ROLE_ADMIN":
@Test
@WithMockUser(roles="ADMIN")
public void requestProtectedUrlWithUser() throws Exception {
mvc
.perform(get("/"))
...
}

Testing HTTP Basic Authentication

While it has always been possible to authenticate with HTTP Basic, it was a bit tedious to remember the
header name, format, and encode the values. Now this can be done using Spring Securitys httpBasic
RequestPostProcessor. For example, the snippet below:
mvc
.perform(get("/").with(httpBasic("user","password")))

will attempt to use HTTP Basic to authenticate a user with the username "user" and the password
"password" by ensuring the following header is populated on the HTTP Request:

4.0.2.RELEASE

Spring Security

Spring Security Reference

Authorization: Basic dXNlcjpwYXNzd29yZA==

10.3 SecurityMockMvcRequestBuilders
Spring MVC Test also provides a RequestBuilder interface that can be used to create the
MockHttpServletRequest used in your test. Spring Security provides a few RequestBuilder
implementations that can be used to make testing easier. In order to use Spring Securitys
RequestBuilder implementations ensure the following static import is used:
import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.*;

Testing Form Based Authentication

You can easily create a request to test a form based authentication using Spring Securitys testing
support. For example, the following will submit a POST to "/login" with the username "user", the
password "password", and a valid CSRF token:
mvc
.perform(formLogin())

It is easy to customize the request. For example, the following will submit a POST to "/auth" with the
username "admin", the password "pass", and a valid CSRF token:
mvc
.perform(formLogin("/auth").user("admin").password("pass"))

We can also customize the parameters names that the username and password are included on. For
example, this is the above request modified to include the username on the HTTP parameter "u" and
the password on the HTTP parameter "p".
mvc
.perform(formLogin("/auth").user("a","admin").password("p","pass"))

Testing Logout
While fairly trivial using standard Spring MVC Test, you can use Spring Securitys testing support to
make testing log out easier. For example, the following will submit a POST to "/logout" with a valid
CSRF token:
mvc
.perform(logout())

You can also customize the URL to post to. For example, the snippet below will submit a POST to "/
signout" with a valid CSRF token:
mvc
.perform(logout("/signout"))

10.4 SecurityMockMvcResultMatchers
At times it is desirable to make various security related assertions about a request. To accommodate this
need, Spring Security Test support implements Spring MVC Tests ResultMatcher interface. In order
to use Spring Securitys ResultMatcher implementations ensure the following static import is used:
import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultMatchers.*;

4.0.2.RELEASE

Spring Security

Spring Security Reference

Unauthenticated Assertion
At times it may be valuable to assert that there is no authenticated user associated with the result of a
MockMvc invocation. For example, you might want to test submitting an invalid username and password
and verify that no user is authenticated. You can easily do this with Spring Securitys testing support
using something like the following:
mvc
.perform(formLogin().password("invalid"))
.andExpect(unauthenticated());

Authenticated Assertion
It is often times that we must assert that an authenticated user exists. For example, we may want to
verify that we authenticated successfully. We could verify that a form based login was successful with
the following snippet of code:
mvc
.perform(formLogin())
.andExpect(authenticated());

If we wanted to assert the roles of the user, we could refine our previous code as shown below:
mvc
.perform(formLogin().user("admin"))
.andExpect(authenticated().withRoles("USER","ADMIN"));

Alternatively, we could verify the username:

mvc
.perform(formLogin().user("admin"))
.andExpect(authenticated().withUsername("admin"));

We can also combine the assertions:

mvc
.perform(formLogin().user("admin").roles("USER","ADMIN"))
.andExpect(authenticated().withUsername("admin"));

4.0.2.RELEASE

Spring Security

Part V. Web Application Security

Most Spring Security users will be using the framework in applications which make user of HTTP
and the Servlet API. In this part, well take a look at how Spring Security provides authentication
and access-control features for the web layer of an application. Well look behind the facade of the
namespace and see which classes and interfaces are actually assembled to provide web-layer security.
In some situations it is necessary to use traditional bean configuration to provide full control over the
configuration, so well also see how to configure these classes directly without the namespace.

Spring Security Reference

11. The Security Filter Chain

Spring Securitys web infrastructure is based entirely on standard servlet filters. It doesnt use servlets
or any other servlet-based frameworks (such as Spring MVC) internally, so it has no strong links to any
particular web technology. It deals in HttpServletRequest s and HttpServletResponse s and
doesnt care whether the requests come from a browser, a web service client, an HttpInvoker or an
AJAX application.
Spring Security maintains a filter chain internally where each of the filters has a particular responsibility
and filters are added or removed from the configuration depending on which services are required. The
ordering of the filters is important as there are dependencies between them. If you have been using
namespace configuration, then the filters are automatically configured for you and you dont have to
define any Spring beans explicitly but here may be times when you want full control over the security
filter chain, either because you are using features which arent supported in the namespace, or you are
using your own customized versions of classes.

11.1 DelegatingFilterProxy
When using servlet filters, you obviously need to declare them in your web.xml, or they will be ignored
by the servlet container. In Spring Security, the filter classes are also Spring beans defined in the
application context and thus able to take advantage of Springs rich dependency-injection facilities and
lifecycle interfaces. Springs DelegatingFilterProxy provides the link between web.xml and the
application context.
When using DelegatingFilterProxy, you will see something like this in the web.xml file:
<filter>
<filter-name>myFilter</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>
<filter-mapping>
<filter-name>myFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>

Notice that the filter is actually a DelegatingFilterProxy, and not the class that will actually
implement the logic of the filter. What DelegatingFilterProxy does is delegate the Filters
methods through to a bean which is obtained from the Spring application
context. This enables the bean to benefit from the Spring web application
context lifecycle support and configuration flexibility. The bean must
implement `javax.servlet.Filter and it must have the same name as that in the filtername element. Read the Javadoc for DelegatingFilterProxy for more information

11.2 FilterChainProxy
Spring Securitys web infrastructure should only be used by delegating to an instance of
FilterChainProxy. The security filters should not be used by themselves. In theory you could
declare each Spring Security filter bean that you require in your application context file and add a
corresponding DelegatingFilterProxy entry to web.xml for each filter, making sure that they
are ordered correctly, but this would be cumbersome and would clutter up the web.xml file quickly
if you have a lot of filters. FilterChainProxy lets us add a single entry to web.xml and deal
entirely with the application context file for managing our web security beans. It is wired using a

4.0.2.RELEASE

Spring Security

Spring Security Reference

DelegatingFilterProxy, just like in the example above, but with the filter-name set to the bean
name "filterChainProxy". The filter chain is then declared in the application context with the same bean
name. Heres an example:
<bean id="filterChainProxy" class="org.springframework.security.web.FilterChainProxy">
<constructor-arg>
<list>
<sec:filter-chain pattern="/restful/**" filters="
securityContextPersistenceFilterWithASCFalse,
basicAuthenticationFilter,
exceptionTranslationFilter,
filterSecurityInterceptor" />
<sec:filter-chain pattern="/**" filters="
securityContextPersistenceFilterWithASCTrue,
formLoginFilter,
exceptionTranslationFilter,
filterSecurityInterceptor" />
</list>
</constructor-arg>
</bean>

The namespace element filter-chain is used for convenience to set up the security filter chain(s)
1
which are required within the application. . It maps a particular URL pattern to a list of filters built
up from the bean names specified in the filters element, and combines them in a bean of type
SecurityFilterChain. The pattern attribute takes an Ant Paths and the most specific URIs should
2
appear first . At runtime the FilterChainProxy will locate the first URI pattern that matches the
current web request and the list of filter beans specified by the filters attribute will be applied to that
request. The filters will be invoked in the order they are defined, so you have complete control over the
filter chain which is applied to a particular URL.
You may have noticed we have declared two SecurityContextPersistenceFilter
s in the filter chain ( ASC is short for allowSessionCreation, a property of
SecurityContextPersistenceFilter). As web services will never present a jsessionid on
future requests, creating HttpSession s for such user agents would be wasteful. If you had a highvolume application which required maximum scalability, we recommend you use the approach shown
above. For smaller applications, using a single SecurityContextPersistenceFilter (with its
default allowSessionCreation as true) would likely be sufficient.
Note that FilterChainProxy does not invoke standard filter lifecycle methods on the filters it
is configured with. We recommend you use Springs application context lifecycle interfaces as an
alternative, just as you would for any other Spring bean.
When we looked at how to set up web security using namespace configuration, we used a
DelegatingFilterProxy with the name "springSecurityFilterChain". You should now be able to see
that this is the name of the FilterChainProxy which is created by the namespace.

Bypassing the Filter Chain

You can use the attribute filters = "none" as an alternative to supplying a filter bean list. This will
omit the request pattern from the security filter chain entirely. Note that anything matching this path will
then have no authentication or authorization services applied and will be freely accessible. If you want
to make use of the contents of the SecurityContext contents during a request, then it must have
1

Note that youll need to include the security namespace in your application context XML file in order to use this syntax. The older
syntax which used a filter-chain-map is still supported, but is deprecated in favour of the constructor argument injection.
2
Instead of a path pattern, the request-matcher-ref attribute can be used to specify a RequestMatcher instance for more
powerful matching

4.0.2.RELEASE

Spring Security

Spring Security Reference

passed through the security filter chain. Otherwise the SecurityContextHolder will not have been
populated and the contents will be null.

11.3 Filter Ordering

The order that filters are defined in the chain is very important. Irrespective of which filters you are
actually using, the order should be as follows:
ChannelProcessingFilter, because it might need to redirect to a different protocol
SecurityContextPersistenceFilter, so a SecurityContext can be set up in the
SecurityContextHolder at the beginning of a web request, and any changes to the
SecurityContext can be copied to the HttpSession when the web request ends (ready for use
with the next web request)
ConcurrentSessionFilter, because it uses the SecurityContextHolder functionality and
needs to update the SessionRegistry to reflect ongoing requests from the principal
Authentication processing mechanisms - UsernamePasswordAuthenticationFilter,
CasAuthenticationFilter,
BasicAuthenticationFilter
etc
so
that
the
SecurityContextHolder can be modified to contain a valid Authentication request token
The SecurityContextHolderAwareRequestFilter, if you are using it to install a Spring
Security aware HttpServletRequestWrapper into your servlet container
The JaasApiIntegrationFilter, if a JaasAuthenticationToken is in the
SecurityContextHolder this will process the FilterChain as the Subject in the
JaasAuthenticationToken
RememberMeAuthenticationFilter, so that if no earlier authentication processing mechanism
updated the SecurityContextHolder, and the request presents a cookie that enables rememberme services to take place, a suitable remembered Authentication object will be put there
AnonymousAuthenticationFilter, so that if no earlier authentication processing mechanism
updated the SecurityContextHolder, an anonymous Authentication object will be put there
ExceptionTranslationFilter, to catch any Spring Security exceptions so that either an HTTP
error response can be returned or an appropriate AuthenticationEntryPoint can be launched
FilterSecurityInterceptor, to protect web URIs and raise exceptions when access is denied

11.4 Request Matching and HttpFirewall

Spring Security has several areas where patterns you have defined are tested against incoming
requests in order to decide how the request should be handled. This occurs when the
FilterChainProxy decides which filter chain a request should be passed through and also when the
FilterSecurityInterceptor decides which security constraints apply to a request. Its important
to understand what the mechanism is and what URL value is used when testing against the patterns
that you define.
The Servlet Specification defines several properties for the HttpServletRequest which are
accessible via getter methods, and which we might want to match against. These are the contextPath,
servletPath, pathInfo and queryString. Spring Security is only interested in securing paths
within the application, so the contextPath is ignored. Unfortunately, the servlet spec does not define

4.0.2.RELEASE

Spring Security

Spring Security Reference

exactly what the values of servletPath and pathInfo will contain for a particular request URI.
4
For example, each path segment of a URL may contain parameters, as defined in RFC 2396 .
The Specification does not clearly state whether these should be included in the servletPath and
pathInfo values and the behaviour varies between different servlet containers. There is a danger that
when an application is deployed in a container which does not strip path parameters from these values,
an attacker could add them to the requested URL in order to cause a pattern match to succeed or fail
5
unexpectedly. . Other variations in the incoming URL are also possible. For example, it could contain
path-traversal sequences (like /../) or multiple forward slashes (//) which could also cause patternmatches to fail. Some containers normalize these out before performing the servlet mapping, but others
dont. To protect against issues like these, FilterChainProxy uses an HttpFirewall strategy to
check and wrap the request. Un-normalized requests are automatically rejected by default, and path
6
parameters and duplicate slashes are removed for matching purposes. . It is therefore essential that
a FilterChainProxy is used to manage the security filter chain. Note that the servletPath and
pathInfo values are decoded by the container, so your application should not have any valid paths
which contain semi-colons, as these parts will be removed for matching purposes.
As mentioned above, the default strategy is to use Ant-style paths for matching and this is likely to be
the best choice for most users. The strategy is implemented in the class AntPathRequestMatcher
which uses Springs AntPathMatcher to perform a case-insensitive match of the pattern against the
concatenated servletPath and pathInfo, ignoring the queryString.
If for some reason, you need a more powerful matching strategy, you can use regular expressions.
The strategy implementation is then`RegexRequestMatcher`. See the Javadoc for this class for more
information.
In practice we recommend that you use method security at your service layer, to control access to your
application, and do not rely entirely on the use of security constraints defined at the web-application
level. URLs change and it is difficult to take account of all the possible URLs that an application might
support and how requests might be manipulated. You should try and restrict yourself to using a few
simple ant paths which are simple to understand. Always try to use a"deny-by-default" approach where
you have a catch-all wildcard ( / or ) defined last and denying access.
Security defined at the service layer is much more robust and harder to bypass, so you should always
take advantage of Spring Securitys method security options.

11.5 Use with other Filter-Based Frameworks

If youre using some other framework that is also filter-based, then you need to make sure that the
Spring Security filters come first. This enables the SecurityContextHolder to be populated in time
for use by the other filters. Examples are the use of SiteMesh to decorate your web pages or a web
framework like Wicket which uses a filter to handle its requests.

11.6 Advanced Namespace Configuration

As we saw earlier in the namespace chapter, its possible to use multiple http elements to define
different security configurations for different URL patterns. Each element creates a filter chain within the
4

users who do not have an admin role. You cant rely on hiding links for security though, as theres
always a possibility that a user will just enter the URL directly in an attempt to bypass the restrictions.
Or they might modify a RESTful URL to change some of the argument values. Your application must
be protected against these scenarios or it will definitely be insecure. You will typically use simple web
layer security to apply constraints to basic URLs and use more specific method-based security on your
service layer interfaces to really nail down what is permissible.
If an AccessDeniedException is thrown and a user has already been authenticated, then this means
that an operation has been attempted for which they dont have enough permissions. In this case,
ExceptionTranslationFilter will invoke a second strategy, the AccessDeniedHandler. By
default, an AccessDeniedHandlerImpl is used, which just sends a 403 (Forbidden) response to the
client. Alternatively you can configure an instance explicitly (as in the above example) and set an error
1
page URL which it will forwards the request to . This can be a simple "access denied" page, such
as a JSP, or it could be a more complex handler such as an MVC controller. And of course, you can
implement the interface yourself and use your own implementation.
Its also possible to supply a custom AccessDeniedHandler when youre using the namespace to
configure your application. See the namespace appendix for more details.

SavedRequest s and the RequestCache Interface

Another of ExceptionTranslationFilters responsibilities is to save the current
request before invoking the `AuthenticationEntryPoint. This allows the request to
be restored after the use has authenticated (see previous overview of web authentication). A typical
example would be where the user logs in with a form, and is then redirected to the original URL by the
default SavedRequestAwareAuthenticationSuccessHandler (see below).
The RequestCache encapsulates the functionality required for storing and retrieving
HttpServletRequest instances. By default the HttpSessionRequestCache is used, which stores
the request in the HttpSession. The RequestCacheFilter has the job of actually restoring the
saved request from the cache when the user is redirected to the original URL.
Under normal circumstances, you shouldnt need to modify any of this functionality, but the savedrequest handling is a "best-effort" approach and there may be situations which the default configuration
isnt able to handle. The use of these interfaces makes it fully pluggable from Spring Security 3.0
onwards.

12.3 SecurityContextPersistenceFilter
We covered the purpose of this all-important filter in the Technical Overview chapter so you might want
to re-read that section at this point. Lets first take a look at how you would configure it for use with a
FilterChainProxy. A basic configuration only requires the bean itself
<bean id="securityContextPersistenceFilter"
class="org.springframework.security.web.context.SecurityContextPersistenceFilter"/>

As we saw previously, this filter has two main tasks. It is responsible for storage of the
SecurityContext contents between HTTP requests and for clearing the SecurityContextHolder
1

We use a forward so that the SecurityContextHolder still contains details of the principal, which may be useful for displaying to
the user. In old releases of Spring Security we relied upon the servlet container to handle a 403 error message, which lacked
this useful contextual information.

4.0.2.RELEASE

Spring Security

Spring Security Reference

when a request is completed. Clearing the ThreadLocal in which the context is stored is essential, as
it might otherwise be possible for a thread to be replaced into the servlet containers thread pool, with
the security context for a particular user still attached. This thread might then be used at a later stage,
performing operations with the wrong credentials.

SecurityContextRepository
From Spring Security 3.0, the job of loading and storing the security context is now delegated to a
separate strategy interface:
public interface SecurityContextRepository {
SecurityContext loadContext(HttpRequestResponseHolder requestResponseHolder);
void saveContext(SecurityContext context, HttpServletRequest request,
HttpServletResponse response);
}

The HttpRequestResponseHolder is simply a container for the incoming request and response
objects, allowing the implementation to replace these with wrapper classes. The returned contents will
be passed to the filter chain.
The default implementation is HttpSessionSecurityContextRepository, which stores the
2
security context as an HttpSession attribute . The most important configuration parameter for this
implementation is the allowSessionCreation property, which defaults to true, thus allowing the
class to create a session if it needs one to store the security context for an authenticated user (it
wont create one unless authentication has taken place and the contents of the security context have
changed). If you dont want a session to be created, then you can set this property to false:
<bean id="securityContextPersistenceFilter"
class="org.springframework.security.web.context.SecurityContextPersistenceFilter">
<property name='securityContextRepository'>
<bean class='org.springframework.security.web.context.HttpSessionSecurityContextRepository'>
<property name='allowSessionCreation' value='false' />
</bean>
</property>
</bean>

Alternatively you could provide an instance of NullSecurityContextRepository, a "http://

en.wikipedia.org/wiki/Null_Object_pattern[null object]" implementation, which will prevent the security
context from being stored, even if a session has already been created during the request.

12.4 UsernamePasswordAuthenticationFilter
Weve now seen the three main filters which are always present in a Spring Security web configuration.
These are also the three which are automatically created by the namespace <http> element and
cannot be substituted with alternatives. The only thing thats missing now is an actual authentication
mechanism, something that will allow a user to authenticate. This filter is the most commonly used
3
authentication filter and the one that is most often customized . It also provides the implementation used
by the <form-login> element from the namespace. There are three stages required to configure it.
2

In Spring Security 2.0 and earlier, this filter was called HttpSessionContextIntegrationFilter and performed all the
work of storing the context was performed by the filter itself. If you were familiar with this class, then most of the configuration
options which were available can now be found on`HttpSessionSecurityContextRepository`.
3
For historical reasons, prior to Spring Security 3.0, this filter was called AuthenticationProcessingFilter and the entry
point was called AuthenticationProcessingFilterEntryPoint. Since the framework now supports many different forms
of authentication, they have both been given more specific names in 3.0.

4.0.2.RELEASE

Spring Security

Spring Security Reference

Configure a LoginUrlAuthenticationEntryPoint with the URL of the login page, just as we

did above, and set it on the ExceptionTranslationFilter.
Implement the login page (using a JSP or MVC controller).
Configure an instance of UsernamePasswordAuthenticationFilter in the application context
Add the filter bean to your filter chain proxy (making sure you pay attention to the order).
The login form simply contains username and password input fields, and posts to the URL that is
monitored by the filter (by default this is /login). The basic filter configuration looks something like this:
<bean id="authenticationFilter" class=
"org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter">
<property name="authenticationManager" ref="authenticationManager"/>
</bean>

Application Flow on Authentication Success and Failure

The filter calls the configured AuthenticationManager to process each authentication
request. The destination following a successful authentication or an authentication failure is
controlled by the AuthenticationSuccessHandler and AuthenticationFailureHandler
strategy interfaces, respectively. The filter has properties which allow you to
4
set these so you can customize the behaviour completely
. Some standard
implementations are supplied such as SimpleUrlAuthenticationSuccessHandler,
SavedRequestAwareAuthenticationSuccessHandler,
SimpleUrlAuthenticationFailureHandler
and
ExceptionMappingAuthenticationFailureHandler. Have a look at the Javadoc for these
classes and also for AbstractAuthenticationProcessingFilter to get an overview of how they
work and the supported features.
If authentication is successful, the resulting Authentication object will be placed into the
SecurityContextHolder. The configured AuthenticationSuccessHandler will then be
called to either redirect or forward the user to the appropriate destination. By default a
SavedRequestAwareAuthenticationSuccessHandler is used, which means that the user will
be redirected to the original destination they requested before they were asked to login.
Note
The ExceptionTranslationFilter caches the original request a user makes. When the user
authenticates, the request handler makes use of this cached request to obtain the original URL
and redirect to it. The original request is then rebuilt and used as an alternative.
If authentication fails, the configured AuthenticationFailureHandler will be invoked.

In versions prior to 3.0, the application flow at this point had evolved to a stage was controlled by a mix of properties on this class
and strategy plugins. The decision was made for 3.0 to refactor the code to make these two strategies entirely responsible.

4.0.2.RELEASE

Spring Security

Spring Security Reference

13. Servlet API integration

This section describes how Spring Security is integrated with the Servlet API. The servletapi-xml sample
application demonstrates the usage of each of these methods.

Since version 3.2, Spring Security is smart enough to no longer automatically save the SecurityContext
on commiting the HttpServletResponse as soon as HttpServletRequest.startAsync() is invoked.

13.3 Servlet 3.1+ Integration

The following section describes the Servlet 3.1 methods that Spring Security integrates with.

HttpServletRequest#changeSessionId()
The HttpServletRequest.changeSessionId() is the default method for protecting against Session
Fixation attacks in Servlet 3.1 and higher.

4.0.2.RELEASE

Spring Security

Spring Security Reference

14. Basic and Digest Authentication

Basic and digest authentiation are alternative authentication mechanisms which are popular in web
applications. Basic authentication is often used with stateless clients which pass their credentials on
each request. Its quite common to use it in combination with form-based authentication where an
application is used through both a browser-based user interface and as a web-service. However, basic
authentication transmits the password as plain text so it should only really be used over an encrypted
transport layer such as HTTPS.

14.1 BasicAuthenticationFilter
BasicAuthenticationFilter is responsible for processing basic authentication credentials
presented in HTTP headers. This can be used for authenticating calls made by Spring remoting protocols
(such as Hessian and Burlap), as well as normal browser user agents (such as Firefox and Internet
Explorer). The standard governing HTTP Basic Authentication is defined by RFC 1945, Section 11,
and BasicAuthenticationFilter conforms with this RFC. Basic Authentication is an attractive
approach to authentication, because it is very widely deployed in user agents and implementation is
extremely simple (its just a Base64 encoding of the username:password, specified in an HTTP header).

Configuration
To implement HTTP Basic Authentication, you need to add a BasicAuthenticationFilter to your
filter chain. The application context should contain BasicAuthenticationFilter and its required
collaborator:
<bean id="basicAuthenticationFilter"
class="org.springframework.security.web.authentication.www.BasicAuthenticationFilter">
<property name="authenticationManager" ref="authenticationManager"/>
<property name="authenticationEntryPoint" ref="authenticationEntryPoint"/>
</bean>
<bean id="authenticationEntryPoint"
class="org.springframework.security.web.authentication.www.BasicAuthenticationEntryPoint">
<property name="realmName" value="Name Of Your Realm"/>
</bean>

The configured AuthenticationManager processes each authentication request. If authentication

fails, the configured AuthenticationEntryPoint will be used to retry the authentication process.
Usually you will use the filter in combination with a`BasicAuthenticationEntryPoint`, which returns a 401
response with a suitable header to retry HTTP Basic authentication. If authentication is successful, the
resulting Authentication object will be placed into the SecurityContextHolder as usual.
If the authentication event was successful, or authentication was not attempted because the
HTTP header did not contain a supported authentication request, the filter chain will continue
as normal. The only time the filter chain will be interrupted is if authentication fails and the
AuthenticationEntryPoint is called.

14.2 DigestAuthenticationFilter
DigestAuthenticationFilter is capable of processing digest authentication credentials
presented in HTTP headers. Digest Authentication attempts to solve many of the weaknesses of
Basic authentication, specifically by ensuring credentials are never sent in clear text across the wire.
Many user agents support Digest Authentication, including FireFox and Internet Explorer. The standard

4.0.2.RELEASE

Spring Security

Spring Security Reference

governing HTTP Digest Authentication is defined by RFC 2617, which updates an earlier version of
the Digest Authentication standard prescribed by RFC 2069. Most user agents implement RFC 2617.
Spring Securitys DigestAuthenticationFilter is compatible with the auth quality of protection
(qop) prescribed by RFC 2617, which also provides backward compatibility with RFC 2069. Digest
Authentication is a more attractive option if you need to use unencrypted HTTP (i.e. no TLS/HTTPS) and
wish to maximise security of the authentication process. Indeed Digest Authentication is a mandatory
requirement for the WebDAV protocol, as noted by RFC 2518 Section 17.1.
Digest Authentication is definitely the most secure choice between Form Authentication, Basic
Authentication and Digest Authentication, although extra security also means more complex user agent
implementations. Central to Digest Authentication is a "nonce". This is a value the server generates.
Spring Securitys nonce adopts the following format:
base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key))
expirationTime:
The date and time when the nonce expires, expressed in milliseconds
key:
A private key to prevent modification of the nonce token

The DigestAuthenticatonEntryPoint has a property specifying the key used for generating the
nonce tokens, along with a nonceValiditySeconds property for determining the expiration time
(default 300, which equals five minutes). Whist ever the nonce is valid, the digest is computed by
concatenating various strings including the username, password, nonce, URI being requested, a clientgenerated nonce (merely a random value which the user agent generates each request), the realm name
etc, then performing an MD5 hash. Both the server and user agent perform this digest computation,
resulting in different hash codes if they disagree on an included value (eg password). In Spring Security
implementation, if the server-generated nonce has merely expired (but the digest was otherwise valid),
the DigestAuthenticationEntryPoint will send a "stale=true" header. This tells the user
agent there is no need to disturb the user (as the password and username etc is correct), but simply
to try again using a new nonce.
An appropriate value for DigestAuthenticationEntryPoints `nonceValiditySeconds
parameter will depend on your application. Extremely secure applications should note that an
intercepted authentication header can be used to impersonate the principal until the expirationTime
contained in the nonce is reached. This is the key principle when selecting an appropriate setting, but
it would be unusual for immensely secure applications to not be running over TLS/HTTPS in the first
instance.
Because of the more complex implementation of Digest Authentication, there are often user agent
issues. For example, Internet Explorer fails to present an opaque token on subsequent requests in
the same session. Spring Security filters therefore encapsulate all state information into the nonce
token instead. In our testing, Spring Securitys implementation works reliably with FireFox and Internet
Explorer, correctly handling nonce timeouts etc.

Configuration
Now that weve reviewed the theory, lets see how to use it. To implement HTTP Digest Authentication,
it is necessary to define DigestAuthenticationFilter in the filter chain. The application context
will need to define the DigestAuthenticationFilter and its required collaborators:

4.0.2.RELEASE

Spring Security

Spring Security Reference

<bean id="digestFilter" class=

"org.springframework.security.web.authentication.www.DigestAuthenticationFilter">
<property name="userDetailsService" ref="jdbcDaoImpl"/>
<property name="authenticationEntryPoint" ref="digestEntryPoint"/>
<property name="userCache" ref="userCache"/>
</bean>
<bean id="digestEntryPoint" class=
"org.springframework.security.web.authentication.www.DigestAuthenticationEntryPoint">
<property name="realmName" value="Contacts Realm via Digest Authentication"/>
<property name="key" value="acegi"/>
<property name="nonceValiditySeconds" value="10"/>
</bean>

The configured UserDetailsService is needed because DigestAuthenticationFilter must

have direct access to the clear text password of a user. Digest Authentication will NOT work if you
1
are using encoded passwords in your DAO . The DAO collaborator, along with the UserCache, are
typically shared directly with a DaoAuthenticationProvider. The authenticationEntryPoint
property must be DigestAuthenticationEntryPoint, so that DigestAuthenticationFilter
can obtain the correct realmName and key for digest calculations.
Like BasicAuthenticationFilter, if authentication is successful an Authentication request
token will be placed into the SecurityContextHolder. If the authentication event was successful,
or authentication was not attempted because the HTTP header did not contain a Digest Authentication
request, the filter chain will continue as normal. The only time the filter chain will be interrupted is if
authentication fails and the AuthenticationEntryPoint is called, as discussed in the previous
paragraph.
Digest Authentications RFC offers a range of additional features to further increase security. For
example, the nonce can be changed on every request. Despite this, Spring Security implementation
was designed to minimise the complexity of the implementation (and the doubtless user agent
incompatibilities that would emerge), and avoid needing to store server-side state. You are invited to
review RFC 2617 if you wish to explore these features in more detail. As far as we are aware, Spring
Securitys implementation does comply with the minimum standards of this RFC.

It is possible to encode the password in the format HEX( MD5(username:realm:password) ) provided the
DigestAuthenticationFilter.passwordAlreadyEncoded is set to true. However, other password encodings will not
work with digest authentication.

4.0.2.RELEASE

Spring Security

Spring Security Reference

15. Remember-Me Authentication

15.1 Overview
Remember-me or persistent-login authentication refers to web sites being able to remember the identity
of a principal between sessions. This is typically accomplished by sending a cookie to the browser,
with the cookie being detected during future sessions and causing automated login to take place.
Spring Security provides the necessary hooks for these operations to take place, and has two concrete
remember-me implementations. One uses hashing to preserve the security of cookie-based tokens and
the other uses a database or other persistent storage mechanism to store the generated tokens.
Note that both implemementations require a UserDetailsService. If you are using an authentication
provider which doesnt use a UserDetailsService (for example, the LDAP provider) then it wont
work unless you also have a UserDetailsService bean in your application context.

15.2 Simple Hash-Based Token Approach

This approach uses hashing to achieve a useful remember-me strategy. In essence a cookie is sent to
the browser upon successful interactive authentication, with the cookie being composed as follows:
base64(username + ":" + expirationTime + ":" +
md5Hex(username + ":" + expirationTime + ":" password + ":" + key))
username:
password:
expirationTime:
key:

As identifiable to the `UserDetailsService`

That matches the one in the retrieved UserDetails
The date and time when the remember-me token expires, expressed in milliseconds
A private key to prevent modification of the remember-me token

As such the remember-me token is valid only for the period specified, and provided that the username,
password and key does not change. Notably, this has a potential security issue in that a captured
remember-me token will be usable from any user agent until such time as the token expires. This is
the same issue as with digest authentication. If a principal is aware a token has been captured, they
can easily change their password and immediately invalidate all remember-me tokens on issue. If more
significant security is needed you should use the approach described in the next section. Alternatively
remember-me services should simply not be used at all.
If you are familiar with the topics discussed in the chapter on namespace configuration, you can enable
remember-me authentication just by adding the <remember-me> element:
<http>
...
<remember-me key="myAppKey"/>
</http>

The UserDetailsService will normally be selected automatically. If you have more than one in
your application context, you need to specify which one should be used with the user-service-ref
attribute, where the value is the name of your UserDetailsService bean.

4.0.2.RELEASE

Spring Security

Spring Security Reference

15.3 Persistent Token Approach

This
approach
is
based
on
the
article
http://jaspan.com/
1
improved_persistent_login_cookie_best_practice with some minor modifications . To use the this
approach with namespace configuration, you would supply a datasource reference:
<http>
...
<remember-me data-source-ref="someDataSource"/>
</http>

The database should contain a persistent_logins table, created using the following SQL (or
equivalent):
create table persistent_logins (username varchar(64) not null,
series varchar(64) primary key,
token varchar(64) not null,
last_used timestamp not null)

15.4 Remember-Me Interfaces and Implementations

Remember-me is used with UsernamePasswordAuthenticationFilter, and is implemented via
hooks in the AbstractAuthenticationProcessingFilter superclass. It is also used within
BasicAuthenticationFilter. The hooks will invoke a concrete RememberMeServices at the
appropriate times. The interface looks like this:
Authentication autoLogin(HttpServletRequest request, HttpServletResponse response);
void loginFail(HttpServletRequest request, HttpServletResponse response);
void loginSuccess(HttpServletRequest request, HttpServletResponse response,
Authentication successfulAuthentication);

Please refer to the JavaDocs for a fuller discussion on what the methods do, although
note at this stage that AbstractAuthenticationProcessingFilter only calls the
loginFail() and loginSuccess() methods. The autoLogin() method is called by
RememberMeAuthenticationFilter whenever the SecurityContextHolder does not contain
an Authentication. This interface therefore provides the underlying remember-me implementation
with sufficient notification of authentication-related events, and delegates to the implementation
whenever a candidate web request might contain a cookie and wish to be remembered. This design
allows any number of remember-me implementation strategies. Weve seen above that Spring Security
provides two implementations. Well look at these in turn.

TokenBasedRememberMeServices
This
implementation
supports
the
simpler
approach
described
in
Section 15.2, Simple Hash-Based Token Approach. TokenBasedRememberMeServices
generates
a
RememberMeAuthenticationToken,
which
is
processed
by
RememberMeAuthenticationProvider. A key is shared between this authentication provider
and the TokenBasedRememberMeServices. In addition, TokenBasedRememberMeServices
requires A UserDetailsService from which it can retrieve the username and password for signature
comparison purposes, and generate the RememberMeAuthenticationToken to contain the correct
1

Essentially, the username is not included in the cookie, to prevent exposing a valid login name unecessarily. There is a discussion
on this in the comments section of this article.

4.0.2.RELEASE

Spring Security

Spring Security Reference

GrantedAuthority s. Some sort of logout command should be provided by the application that
invalidates the cookie if the user requests this. TokenBasedRememberMeServices also implements
Spring Securitys LogoutHandler interface so can be used with LogoutFilter to have the cookie
cleared automatically.
The beans required in an application context to enable remember-me services are as follows:
<bean id="rememberMeFilter" class=
"org.springframework.security.web.authentication.rememberme.RememberMeAuthenticationFilter">
<property name="rememberMeServices" ref="rememberMeServices"/>
<property name="authenticationManager" ref="theAuthenticationManager" />
</bean>
<bean id="rememberMeServices" class=
"org.springframework.security.web.authentication.rememberme.TokenBasedRememberMeServices">
<property name="userDetailsService" ref="myUserDetailsService"/>
<property name="key" value="springRocks"/>
</bean>
<bean id="rememberMeAuthenticationProvider" class=
"org.springframework.security.authentication.RememberMeAuthenticationProvider">
<property name="key" value="springRocks"/>
</bean>

Dont
forget
to
add
your
RememberMeServices
implementation
to
your
UsernamePasswordAuthenticationFilter.setRememberMeServices() property, include the
RememberMeAuthenticationProvider in your AuthenticationManager.setProviders()
list, and add RememberMeAuthenticationFilter into your FilterChainProxy (typically
immediately after your UsernamePasswordAuthenticationFilter).

PersistentTokenBasedRememberMeServices
This class can be used in the same way as TokenBasedRememberMeServices, but it additionally
needs to be configured with a PersistentTokenRepository to store the tokens. There are two
standard implementations.
InMemoryTokenRepositoryImpl which is intended for testing only.
JdbcTokenRepositoryImpl which stores the tokens in a database.
The database schema is described above in Section 15.3, Persistent Token Approach.

4.0.2.RELEASE

Spring Security

Spring Security Reference

16. Cross Site Request Forgery (CSRF)

This section discusses Spring Securitys Cross Site Request Forgery (CSRF) support.

16.1 CSRF Attacks

Before we discuss how Spring Security can protect applications from CSRF attacks, we will explain
what a CSRF attack is. Lets take a look at a concrete example to get a better understanding.
Assume that your banks website provides a form that allows transferring money from the currently
logged in user to another bank account. For example, the HTTP request might look like:
POST /transfer HTTP/1.1
Host: bank.example.com
Cookie: JSESSIONID=randomid; Domain=bank.example.com; Secure; HttpOnly
Content-Type: application/x-www-form-urlencoded
amount=100.00&routingNumber=1234&account=9876

Now pretend you authenticate to your banks website and then, without logging out, visit an evil website.
The evil website contains an HTML page with the following form:
<form action="https://bank.example.com/transfer" method="post">
<input type="hidden"
name="amount"
value="100.00"/>
<input type="hidden"
name="routingNumber"
value="evilsRoutingNumber"/>
<input type="hidden"
name="account"
value="evilsAccountNumber"/>
<input type="submit"
value="Win Money!"/>
</form>

You like to win money, so you click on the submit button. In the process, you have unintentionally
transferred $100 to a malicious user. This happens because, while the evil website cannot see your
cookies, the cookies associated with your bank are still sent along with the request.
Worst yet, this whole process could have been automated using JavaScript. This means you didnt even
need to click on the button. So how do we protect ourselves from such attacks?

16.2 Synchronizer Token Pattern

The issue is that the HTTP request from the banks website and the request from the evil website are
exactly the same. This means there is no way to reject requests coming from the evil website and allow
requests coming from the banks website. To protect against CSRF attacks we need to ensure there is
something in the request that the evil site is unable to provide.
One solution is to use the Synchronizer Token Pattern. This solution is to ensure that each request
requires, in addition to our session cookie, a randomly generated token as an HTTP parameter. When
a request is submitted, the server must look up the expected value for the parameter and compare it
against the actual value in the request. If the values do not match, the request should fail.
We can relax the expectations to only require the token for each HTTP request that updates state.
This can be safely done since the same origin policy ensures the evil site cannot read the response.

4.0.2.RELEASE

Spring Security

Spring Security Reference

Additionally, we do not want to include the random token in HTTP GET as this can cause the tokens
to be leaked.
Lets take a look at how our example would change. Assume the randomly generated token is present
in an HTTP parameter named _csrf. For example, the request to transfer money would look like this:
POST /transfer HTTP/1.1
Host: bank.example.com
Cookie: JSESSIONID=randomid; Domain=bank.example.com; Secure; HttpOnly
Content-Type: application/x-www-form-urlencoded
amount=100.00&routingNumber=1234&account=9876&_csrf=<secure-random>

You will notice that we added the _csrf parameter with a random value. Now the evil website will not
be able to guess the correct value for the _csrf parameter (which must be explicitly provided on the evil
website) and the transfer will fail when the server compares the actual token to the expected token.

16.3 When to use CSRF protection

When should you use CSRF protection? Our recommendation is to use CSRF protection for any request
that could be processed by a browser by normal users. If you are only creating a service that is used
by non-browser clients, you will likely want to disable CSRF protection.

CSRF protection and JSON

A common question is "do I need to protect JSON requests made by javascript?" The short answer
is, it depends. However, you must be very careful as there are CSRF exploits that can impact JSON
requests. For example, a malicious user can create a CSRF with JSON using the following form:
<form action="https://bank.example.com/transfer" method="post" enctype="text/plain">
<input name='{"amount":100,"routingNumber":"evilsRoutingNumber","account":"evilsAccountNumber",
"ignore_me":"' value='test"}' type='hidden'>
<input type="submit"
value="Win Money!"/>
</form>

This will produce the following JSON structure

{ "amount": 100,
"routingNumber": "evilsRoutingNumber",
"account": "evilsAccountNumber",
"ignore_me": "=test"
}

If an application were not validating the Content-Type, then it would be exposed to this exploit.
Depending on the setup, a Spring MVC application that validates the Content-Type could still be
exploited by updating the URL suffix to end with ".json" as shown below:
<form action="https://bank.example.com/transfer.json" method="post" enctype="text/plain">
<input name='{"amount":100,"routingNumber":"evilsRoutingNumber","account":"evilsAccountNumber",
"ignore_me":"' value='test"}' type='hidden'>
<input type="submit"
value="Win Money!"/>
</form>

CSRF and Stateless Browser Applications

What if my application is stateless? That doesnt necessarily mean you are protected. In fact, if a
user does not need to perform any actions in the web browser for a given request, they are likely still
vulnerable to CSRF attacks.

4.0.2.RELEASE

Spring Security

Spring Security Reference

For example, consider an application uses a custom cookie that contains all the state within it for
authentication instead of the JSESSIONID. When the CSRF attack is made the custom cookie will
be sent with the request in the same manner that the JSESSIONID cookie was sent in our previous
example.
Users using basic authentication are also vulnerable to CSRF attacks since the browser will
automatically include the username password in any requests in the same manner that the JSESSIONID
cookie was sent in our previous example.

16.4 Using Spring Security CSRF Protection

So what are the steps necessary to use Spring Securitys to protect our site against CSRF attacks? The
steps to using Spring Securitys CSRF protection are outlined below:
Use proper HTTP verbs
Configure CSRF Protection
Include the CSRF Token

Use proper HTTP verbs

The first step to protecting against CSRF attacks is to ensure your website uses proper HTTP verbs.
Specifically, before Spring Securitys CSRF support can be of use, you need to be certain that your
application is using PATCH, POST, PUT, and/or DELETE for anything that modifies state.
This is not a limitation of Spring Securitys support, but instead a general requirement for proper CSRF
prevention. The reason is that including private information in an HTTP GET can cause the information to
be leaked. See RFC 2616 Section 15.1.3 Encoding Sensitive Information in URIs for general guidance
on using POST instead of GET for sensitive information.

Configure CSRF Protection

The next step is to include Spring Securitys CSRF protection within your application. Some frameworks
handle invalid CSRF tokens by invaliding the users session, but this causes its own problems. Instead
by default Spring Securitys CSRF protection will produce an HTTP 403 access denied. This can
be customized by configuring the AccessDeniedHandler to process InvalidCsrfTokenException
differently.
As of Spring Security 4.0, CSRF protection is enabled by default with XML configuration. If you would
like to disable CSRF protection, the corresponding XML configuration can be seen below.
<http>

<csrf disabled="true"/>
</http>

CSRF protection is enabled by default with Java configuration. If you would like to disable CSRF,
the corresponding Java configuration can be seen below. Refer to the Javadoc of csrf() for additional
customizations in how CSRF protection is configured.

4.0.2.RELEASE

Spring Security

Spring Security Reference

@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
.csrf().disable();
}
}

Include the CSRF Token

Form Submissions
The last step is to ensure that you include the CSRF token in all PATCH, POST, PUT, and DELETE
methods. One way to approach this is to use the _csrf request attribute to obtain the current
CsrfToken. An example of doing this with a JSP is shown below:
<c:url var="logoutUrl" value="/logout"/>
<form action="${logoutUrl}"
method="post">
<input type="submit"
value="Log out" />
<input type="hidden"
name="${_csrf.parameterName}"
value="${_csrf.token}"/>
</form>

An easier approach is to use the csrfInput tag from the Spring Security JSP tag library.
Note
If you are using Spring MVC <form:form> tag or Thymeleaf 2.1+ and are using
@EnableWebSecurity, the CsrfToken is automatically included for you (using the
CsrfRequestDataValueProcessor).
Ajax and JSON Requests
If you are using JSON, then it is not possible to submit the CSRF token within an HTTP parameter.
Instead you can submit the token within a HTTP header. A typical pattern would be to include the CSRF
token within your meta tags. An example with a JSP is shown below:
<html>
<head>
<meta name="_csrf" content="${_csrf.token}"/>

<meta name="_csrf_header" content="${_csrf.headerName}"/>

</head>

Instead of manually creating the meta tags, you can use the simpler csrfMetaTags tag from the Spring
Security JSP tag library.
You can then include the token within all your Ajax requests. If you were using jQuery, this could be
done with the following:

4.0.2.RELEASE

Spring Security

Spring Security Reference

$(function () {
var token = $("meta[name='_csrf']").attr("content");
var header = $("meta[name='_csrf_header']").attr("content");
$(document).ajaxSend(function(e, xhr, options) {
xhr.setRequestHeader(header, token);
});
});

As an alternative to jQuery, we recommend using cujoJSs rest.js. The rest.js module provides advanced
support for working with HTTP requests and responses in RESTful ways. A core capability is the ability
to contextualize the HTTP client adding behavior as needed by chaining interceptors on to the client.
var client = rest.chain(csrf, {
token: $("meta[name='_csrf']").attr("content"),
name: $("meta[name='_csrf_header']").attr("content")
});

The configured client can be shared with any component of the application that needs to make a
request to the CSRF protected resource. One significant different between rest.js and jQuery is that only
requests made with the configured client will contain the CSRF token, vs jQuery where all requests will
include the token. The ability to scope which requests receive the token helps guard against leaking the
CSRF token to a third party. Please refer to the rest.js reference documentation for more information
on rest.js.

16.5 CSRF Caveats

There are a few caveats when implementing CSRF.

100

Spring Security Reference

For example, you can provide a custom CsrfTokenRepository to override the way in which the
CsrfToken is stored.
You can also specify a custom RequestMatcher to determine which requests are protected by CSRF
(i.e. perhaps you dont care if log out is exploited). In short, if Spring Securitys CSRF protection
doesnt behave exactly as you want it, you are able to customize the behavior. Refer to the the
section called <csrf> documentation for details on how to make these customizations with XML and
the CsrfConfigurer javadoc for details on how to make these customizations when using Java
configuration.

4.0.2.RELEASE

Spring Security

101

Spring Security Reference

17. Security HTTP Response Headers

This section discusses Spring Securitys support for adding various security headers to the response.

17.1 Default Security Headers

Spring Security allows users to easily inject the default security headers to assist in protecting their
application. The default for Spring Security is to include the following headers:
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block

Note
Strict-Transport-Security is only added on HTTPS requests
For additional details on each of these headers, refer to the corresponding sections:
Cache Control
Content Type Options
HTTP Strict Transport Security
X-Frame-Options
X-XSS-Protection
While each of these headers are considered best practice, it should be noted that not all clients utilize
the headers, so additional testing is encouraged.
You can customize specific headers. For example, assume that want your HTTP response headers to
look like the following:
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

Specifically, you want all of the default headers with the following customizations:
X-Frame-Options to allow any request from same domain
HTTP Strict Transport Security (HSTS) will not be addded to the response
You can easily do this with the following Java Configuration:

4.0.2.RELEASE

Spring Security

102

Spring Security Reference

@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers()
.frameOptions()
.sameOrigin()
.and()
.hsts().disable();
}
}

Alternatively, if you are using Spring Security XML Configuration, you can use the following:
<http>

<headers>
<frame-options policy="SAMEORIGIN" />
<hsts disable="true"/>
</headers>
</http>

If you do not want the defaults to be added and want explicit control over what should be used, you can
disable the defaults. An example for both Java and XML based configuration is provided below:
If you are using Spring Securitys Java Configuration the following will only add Cache Control.
@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers()
// do not use any default headers unless explicitly listed
.defaultsDisabled()
.cacheControl();
}
}

The following XML will only add Cache Control.

If necessary, you can disable all of the HTTP Security response headers with the following Java
Configuration:

4.0.2.RELEASE

Spring Security

103

Spring Security Reference

@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers().disable();
}
}

If necessary, you can disable all of the HTTP Security response headers with the following XML
configuration below:
<http>

<headers disabled="true" />
</http>

Cache Control
In the past Spring Security required you to provide your own cache control for your web application.
This seemed reasonable at the time, but browser caches have evolved to include caches for secure
connections as well. This means that a user may view an authenticated page, log out, and then a
malicious user can use the browser history to view the cached page. To help mitigate this Spring Security
has added cache control support which will insert the following headers into you response.
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0

Similarly, you can customize xss protection within Java Configuration with the following:
@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers()
.xssProtection()
.block(false);
}
}

17.2 Custom Headers

Spring Security has mechanisms to make it convenient to add the more common security headers to
your application. However, it also provides hooks to enable adding custom headers.

Static Headers
There may be times you wish to inject custom security headers into your application that are not
supported out of the box. For example, perhaps you wish to have early support for Content Security

4.0.2.RELEASE

Spring Security

108

Spring Security Reference

Policy in order to ensure that resources are only loaded from the same origin. Since support for
Content Security Policy has not been finalized, browsers use one of two common extension headers to
implement the feature. This means we will need to inject the policy twice. An example of the headers
can be seen below:
X-Content-Security-Policy: default-src 'self'
X-WebKit-CSP: default-src 'self'

When using the XML namespace, these headers can be added to the response using the <header>
element as shown below:
<http>

<headers>
<header name="X-Content-Security-Policy" value="default-src 'self'"/>
<header name="X-WebKit-CSP" value="default-src 'self'"/>
</headers>
</http>

Similarly, the headers could be added to the response using Java Configuration as shown in the
following:
@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers()
.addHeaderWriter(new StaticHeadersWriter("X-Content-Security-Policy","default-src 'self'"))
.addHeaderWriter(new StaticHeadersWriter("X-WebKit-CSP","default-src 'self'"));
}
}

Headers Writer
When the namespace or Java configuration does not support the headers you want, you can create a
custom HeadersWriter instance or even provide a custom implementation of the HeadersWriter.
Lets take a look at an example of using an custom instance of XFrameOptionsHeaderWriter.
Perhaps you want to allow framing of content for the same origin. This is easily supported by setting the
policy attribute to "SAMEORIGIN", but lets take a look at a more explicit example using the ref attribute.
<http>

<headers>
<header ref="frameOptionsWriter"/>
</headers>
</http>

<beans:bean id="frameOptionsWriter"
class="org.springframework.security.web.header.writers.frameoptions.XFrameOptionsHeaderWriter"
c:frameOptionsMode="SAMEORIGIN"/>

We could also restrict framing of content to the same origin with Java configuration:

4.0.2.RELEASE

Spring Security

109

Spring Security Reference

@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers()
.addHeaderWriter(new XFrameOptionsHeaderWriter(XFrameOptionsMode.SAMEORIGIN));
}
}

DelegatingRequestMatcherHeaderWriter
At times you may want to only write a header for certain requests. For example, perhaps
you want to only protect your log in page from being framed. You could use the
DelegatingRequestMatcherHeaderWriter to do so. When using the XML namespace
configuration, this can be done with the following:
<http>

<headers>
<frame-options disabled="true"/>
<header ref="headerWriter"/>
</headers>
</http>
<beans:bean id="headerWriter"
class="org.springframework.security.web.header.writers.DelegatingRequestMatcherHeaderWriter">
<beans:constructor-arg>
<bean class="org.springframework.security.web.util.matcher.AntPathRequestMatcher"
c:pattern="/login"/>
</beans:constructor-arg>
<beans:constructor-arg>
<beans:bean
class="org.springframework.security.web.header.writers.frameoptions.XFrameOptionsHeaderWriter"/>
</beans:constructor-arg>
</beans:bean>

We could also prevent framing of content to the log in page using java configuration:
@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
RequestMatcher matcher = new AntPathRequestMatcher("/login");
DelegatingRequestMatcherHeaderWriter headerWriter =
new DelegatingRequestMatcherHeaderWriter(matcher,new XFrameOptionsHeaderWriter());
http
// ...
.headers()
.frameOptions().disabled()
.addHeaderWriter(headerWriter);
}
}

4.0.2.RELEASE

Spring Security

110

Spring Security Reference

18. Session Management

HTTP session related functonality is handled by a combination of the SessionManagementFilter
and the SessionAuthenticationStrategy interface, which the filter delegates to. Typical usage
includes session-fixation protection attack prevention, detection of session timeouts and restrictions on
how many sessions an authenticated user may have open concurrently.

18.1 SessionManagementFilter
The SessionManagementFilter checks the contents of the SecurityContextRepository
against the current contents of the SecurityContextHolder to determine whether a user has
been authenticated during the current request, typically by a non-interactive authentication mechanism,
1
such as pre-authentication or remember-me . If the repository contains a security context, the filter
does nothing. If it doesnt, and the thread-local SecurityContext contains a (non-anonymous)
Authentication object, the filter assumes they have been authenticated by a previous filter in the
stack. It will then invoke the configured SessionAuthenticationStrategy.
If the user is not currently authenticated, the filter will check whether an invalid session ID has been
requested (because of a timeout, for example) and will invoke the configured`InvalidSessionStrategy`,
if one is set. The most common behaviour is just to redirect to a fixed URL and this is encapsulated
in the standard implementation`SimpleRedirectInvalidSessionStrategy`. The latter is also used when
configuring an invalid session URL through the namespace,as described earlier.

18.2 SessionAuthenticationStrategy
SessionAuthenticationStrategy is used by both SessionManagementFilter and
AbstractAuthenticationProcessingFilter, so if you are using a customized form-login class,
for example, you will need to inject it into both of these. In this case, a typical configuration, combining
the namespace and custom beans might look like this:
<http>
<custom-filter position="FORM_LOGIN_FILTER" ref="myAuthFilter" />
<session-management session-authentication-strategy-ref="sas"/>
</http>
<beans:bean id="myAuthFilter" class=
"org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter">
<beans:property name="sessionAuthenticationStrategy" ref="sas" />
...
</beans:bean>
<beans:bean id="sas" class=
"org.springframework.security.web.authentication.session.SessionFixationProtectionStrategy" />

Note that the use of the default, SessionFixationProtectionStrategy may cause issues if you
are storing beans in the session which implement HttpSessionBindingListener, including Spring
session-scoped beans. See the Javadoc for this class for more information.

18.3 Concurrency Control

Spring Security is able to prevent a principal from concurrently authenticating to the same application
more than a specified number of times. Many ISVs take advantage of this to enforce licensing, whilst
1

Authentication by mechanisms which perform a redirect after authenticating (such as form-login) will not be detected
by`SessionManagementFilter`, as the filter will not be invoked during the authenticating request. Session-management
functionality has to be handled separately in these cases.

4.0.2.RELEASE

Spring Security

111

Spring Security Reference

network administrators like this feature because it helps prevent people from sharing login names. You
can, for example, stop user"Batman" from logging onto the web application from two different sessions.
You can either expire their previous login or you can report an error when they try to log in again,
preventing the second login. Note that if you are using the second approach, a user who has not explicitly
logged out (but who has just closed their browser, for example) will not be able to log in again until their
original session expires.
Concurrency control is supported by the namespace, so please check the earlier namespace chapter
for the simplest configuration. Sometimes you need to customize things though.
The implementation uses a specialized version of SessionAuthenticationStrategy, called
ConcurrentSessionControlAuthenticationStrategy.
Note
Previously the concurrent authentication check was made by the ProviderManager, which
could be injected with a ConcurrentSessionController. The latter would check if the user
was attempting to exceed the number of permitted sessions. However, this approach required that
an HTTP session be created in advance, which is undesirable. In Spring Security 3, the user is first
authenticated by the AuthenticationManager and once they are successfully authenticated, a
session is created and the check is made whether they are allowed to have another session open.
To use concurrent session support, youll need to add the following to web.xml:
<listener>
<listener-class>
org.springframework.security.web.session.HttpSessionEventPublisher
</listener-class>
</listener>

In addition, you will need to add the ConcurrentSessionFilter to your FilterChainProxy. The
ConcurrentSessionFilter requires two properties, sessionRegistry, which generally points to
an instance of SessionRegistryImpl, and expiredUrl, which points to the page to display when
a session has expired. A configuration using the namespace to create the FilterChainProxy and
other default beans might look like this:

4.0.2.RELEASE

Spring Security

112

Spring Security Reference

<beans:bean id="sas" class="org.springframework.security.web.authentication.session.CompositeSessionAuthenticationStrategy"

<beans:constructor-arg>
<beans:list>
<beans:bean class="org.springframework.security.web.authentication.session.ConcurrentSessionControlAuthenticationStrategy"
<beans:constructor-arg ref="sessionRegistry"/>
<beans:property name="maximumSessions" value="1" />
<beans:property name="exceptionIfMaximumExceeded" value="true" />
</beans:bean>
<beans:bean class="org.springframework.security.web.authentication.session.SessionFixationProtectionStrategy">
</beans:bean>
<beans:bean class="org.springframework.security.web.authentication.session.RegisterSessionAuthenticationStrategy">
<beans:constructor-arg ref="sessionRegistry"/>
</beans:bean>
</beans:list>
</beans:constructor-arg>
</beans:bean>
<beans:bean id="sessionRegistry"
class="org.springframework.security.core.session.SessionRegistryImpl" />

Adding the listener to web.xml causes an ApplicationEvent to be published to the Spring

ApplicationContext every time a HttpSession commences or terminates. This is critical, as it
allows the SessionRegistryImpl to be notified when a session ends. Without it, a user will never
be able to log back in again once they have exceeded their session allowance, even if they log out of
another session or it times out.

115

Spring Security Reference

20. WebSocket Security

Spring Security 4 added support for securing Springs WebSocket support. This section describes how
to use Spring Securitys WebSocket support.
Note
You can find a complete working sample of WebSocket security in samples/chat-jc.

Direct JSR-356 Support

Spring Security does not provide direct JSR-356 support because doing so would provide little
value. This is because the format is unknown, so there is little Spring can do to secure an unknown
format. Additionally, JSR-356 does not provide a way to intercept messages, so security would
be rather invasive.

20.1 WebSocket Configuration

This will ensure that:

Any inbound CONNECT message requires a valid CSRF token to enforce Same Origin Policy

The SecurityContextHolder is populated with the user within the simpUser header attribute for any
inbound request.
Our messages require the proper authorization. Specifically, any inbound message that starts with
"/user/" will require ROLE_USER. Additional details on authorization can be found in Section 20.3,
WebSocket Authorization

Spring Security also provides XML Namespace support for securing WebSockets. A comparable XML
based configuration looks like the following:
<websocket-message-broker>

<intercept-message pattern="/user/**" access="hasRole('USER')" />

</websocket-message-broker>

This will ensure that:

Any inbound CONNECT message requires a valid CSRF token to enforce Same Origin Policy

4.0.2.RELEASE

Spring Security

116

Spring Security Reference

20.2 WebSocket Authentication

WebSockets reuse the same authentication information that is found in the HTTP request when the
WebSocket connection was made. This means that the Principal on the HttpServletRequest
will be handed off to WebSockets. If you are using Spring Security, the Principal on the
HttpServletRequest is overridden automatically.
More concretely, to ensure a user has authenticated to your WebSocket application, all that is necessary
is to ensure that you setup Spring Security to authenticate your HTTP based web application.

20.3 WebSocket Authorization

Spring Security 4.0 has introduced authorization support for WebSockets through the
Spring Messaging abstraction. To configure authorization using Java Configuration, simply
extend the AbstractSecurityWebSocketMessageBrokerConfigurer and configure the
MessageSecurityMetadataSourceRegistry. For example:
@Configuration
public class WebSocketSecurityConfig extends AbstractSecurityWebSocketMessageBrokerConfigurer {
@Override
protected void configureInbound(MessageSecurityMetadataSourceRegistry messages) {
messages
.nullDestMatcher().authenticated()
.simpSubscribeDestMatchers("/user/queue/errors").permitAll()
.simpDestMatchers("/app/**").hasRole("USER")
.simpSubscribeDestMatchers("/user/**", "/topic/friends/*").hasRole("USER")
.simpTypeMatchers(MESSAGE, SUBSCRIBE).denyAll()
.anyMessage().denyAll();
}
}

This will ensure that:

Any message without a destination (i.e. anything other that Message type of MESSAGE or
SUBSCRIBE) will require the user to be authenticated
Anyone can subscribe to /user/queue/errors
Any message that has a destination starting with "/app/" will be require the user to have the role
ROLE_USER
Any message that starts with "/user/" or "/topic/friends/" that is of type SUBSCRIBE will require
ROLE_USER
Any other message of type MESSAGE or SUBSCRIBE is rejected. Due to 6 we do not need this
step, but it illustrates how one can match on specific message types.
Any other Message is rejected. This is a good idea to ensure that you do not miss any messages.

Spring Security also provides XML Namespace support for securing WebSockets. A comparable XML
based configuration looks like the following:

4.0.2.RELEASE

Spring Security

117

Spring Security Reference

<websocket-message-broker>

<intercept-message type="CONNECT" access="permitAll" />

<intercept-message type="UNSUBSCRIBE" access="permitAll" />
<intercept-message type="DISCONNECT" access="permitAll" />
<intercept-message pattern="/user/queue/errors" type="SUBSCRIBE" access="permitAll" />
<intercept-message pattern="/app/**" access="hasRole('USER')" />

<intercept-message pattern="/user/**" access="hasRole('USER')" />

<intercept-message pattern="/topic/friends/*" access="hasRole('USER')" />

<intercept-message type="MESSAGE" access="denyAll" />

<intercept-message type="SUBSCRIBE" access="denyAll" />
<intercept-message pattern="/**" access="denyAll" />
</websocket-message-broker>

This will ensure that:

Any message of type CONNECT, UNSUBSCRIBE, or DISCONNECT will require the user to be
authenticated
Anyone can subscribe to /user/queue/errors
Any message that has a destination starting with "/app/" will be require the user to have the role
ROLE_USER
Any message that starts with "/user/" or "/topic/friends/" that is of type SUBSCRIBE will require
ROLE_USER
Any other message of type MESSAGE or SUBSCRIBE is rejected. Due to 6 we do not need this
step, but it illustrates how one can match on specific message types.
Any other message with a destination is rejected. This is a good idea to ensure that you do not
miss any messages.

WebSocket Authorization Notes

In order to properly secure your application it is important to understand Springs WebSocket support.
WebSocket Authorization on Message Types
It is important to understand the distinction between SUBSCRIBE and MESSAGE types of messages
and how it works within Spring.
Consider a chat application.
The system can send notifications MESSAGE to all users through a destination of "/topic/system/
notifications"
Clients can receive notifications by SUBSCRIBE to the "/topic/system/notifications".
While we want clients to be able to SUBSCRIBE to "/topic/system/notifications", we do not want to enable
them to send a MESSAGE to that destination. If we allowed sending a MESSAGE to "/topic/system/
notifications", then clients could send a message directly to that endpoint and impersonate the system.
In general, it is common for applications to deny any MESSAGE sent to a message that starts with the
broker prefix (i.e. "/topic/" or "/queue/").

4.0.2.RELEASE

Spring Security

118

Spring Security Reference

WebSocket Authorization on Destinations

It is also is important to understand how destinations are transformed.
Consider a chat application.
Users can send messages to a specific user by sending a message to the destination of "/app/chat".
The application sees the message, ensures that the "from" attribute is specified as the current user
(we cannot trust the client).
The
application
then
sends
the
message
to
the
recipient
using
SimpMessageSendingOperations.convertAndSendToUser("toUser",
"/queue/
messages", message).
The message gets turned into the destination of "/queue/user/messages-<sessionid>"
With the application above, we want to allow our client to listen to "/user/queue" which is transformed
into "/queue/user/messages-<sessionid>". However, we do not want the client to be able to listen to "/
queue/*" because that would allow the client to see messages for every user.
In general, it is common for applications to deny any SUBSCRIBE sent to a message that starts with the
broker prefix (i.e. "/topic/" or "/queue/"). Of course we may provide exceptions to account for things like

Outbound Messages
Spring contains a section titled Flow of Messages that describes how messages flow through the system.
It is important to note that Spring Security only secures the clientInboundChannel. Spring Security
does not attempt to secure the clientOutboundChannel.
The most important reason for this is performance. For every message that goes in, there are typically
many many more that go out. Instead of securing the outbound messages, we encourage securing the
subscription to the endpoints.

20.4 Enforcing Same Origin Policy

It is important to emphasize that the browser does not enforce the Same Origin Policy for WebSocket
connections. This is an extremely important consideration.

Why Same Origin?

Consider the following scenario. A user visits bank.com and authenticates to their account. The same
user opens another tab in their browser and visits evil.com. The Same Origin Policy ensures that evil.com
cannot read or write data to bank.com.
With WebSockets the Same Origin Policy does not apply. In fact, unless bank.com explicitly forbids it,
evil.com can read and write data on behalf of the user. This means that anything the user can do over
the websocket (i.e. transfer money), evil.com can do on that users behalf.
Since SockJS tries to emulate WebSockets it also bypasses the Same Origin Policy. This means
developers need to explicitly protect their applications from external domains when using SockJS.

Spring WebSocket Allowed Origin

Fortunately, since Spring 4.1.5 Springs WebSocket and SockJS support restricts access to the current
domain. Spring Security adds an additional layer of protection to provide defence in depth.

4.0.2.RELEASE

Spring Security

119

Spring Security Reference

Adding CSRF to Stomp Headers

By default Spring Security requires the CSRF token in any CONNECT message type. This ensures that
only a site that has access to the CSRF token can connect. Since only the Same Origin can access
the CSRF token, external domains are not allowed to make a connection.
Typically we need to include the CSRF token in an HTTP header or an HTTP parameter. However,
SockJS does not allow for these options. Instead, we must include the token in the Stomp headers
Applications can obtain a CSRF token by accessing the request attribute named _csrf. For example,
the following will allow accessing the CsrfToken in a JSP:
var headerName = "${_csrf.headerName}";
var token = "${_csrf.token}";

If you are using static HTML, you can expose the CsrfToken on a REST endpoint. For example, the
following would expose the CsrfToken on the URL /csrf
@RestController
public class CsrfController {
@RequestMapping("/csrf")
public CsrfToken csrf(CsrfToken token) {
return token;
}
}

The javascript can make a REST call to the endpoint and use the response to populate the headerName
and the token.
We can now include the token in our Stomp client. For example:
...
var headers = {};
headers[headerName] = token;
stompClient.connect(headers, function(frame) {
...
}

Disable CSRF within WebSockets

If you want to allow other domains to access your site, you can disable Spring Securitys protection. For
example, in Java Configuration you can use the following:
@Configuration
public class WebSocketSecurityConfig extends AbstractSecurityWebSocketMessageBrokerConfigurer {
...
@Override
protected boolean sameOriginDisabled() {
return true;
}
}

20.5 Working with SockJS

SockJS provides fallback transports to support older browsers. When using the fallback options we need
to relax a few security constraints to allow SockJS to work with Spring Security.

4.0.2.RELEASE

Spring Security

120

Spring Security Reference

SockJS & frame-options

SockJS may use an transport that leverages an iframe. By default Spring Security will deny the site
from being framed to prevent Clickjacking attacks. To allow SockJS frame based transports to work, we
need to configure Spring Security to allow the same origin to frame the content.
You can customize X-Frame-Options with the frame-options element. For example, the following will
instruct Spring Security to use "X-Frame-Options: SAMEORIGIN" which allows iframes within the same
domain:
<http>

<headers>
<frame-options
policy="SAMEORIGIN" />
</headers>
</http>

Similarly, you can customize frame options to use the same origin within Java Configuration using the
following:
@EnableWebSecurity
public class WebSecurityConfig extends
WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
// ...
.headers()
.frameOptions()
.sameOrigin();
}
}

SockJS & Relaxing CSRF

SockJS uses a POST on the CONNECT messages for any HTTP based transport. Typically we need
to include the CSRF token in an HTTP header or an HTTP parameter. However, SockJS does not allow
for these options. Instead, we must include the token in the Stomp headers as described in the section
called Adding CSRF to Stomp Headers.
It also means we need to relax our CSRF protection with the web layer. Specifically, we want to disable
CSRF protection for our connect URLs. We do NOT want to disable CSRF protection for every URL.
Otherwise our site will be vulnerable to CSRF attacks.
We can easily achieve this by providing a CSRF RequestMatcher. Our Java Configuration makes this
extremely easy. For example, if our stomp endpoint is "/chat" we can disable CSRF protection for only
URLs that start with "/chat/" using the following configuration:

4.0.2.RELEASE

Spring Security

121

Spring Security Reference

@Configuration
@EnableWebSecurity
public class WebSecurityConfig
extends WebSecurityConfigurerAdapter {
@Override
protected void configure(HttpSecurity http) throws Exception {
http
.csrf()
// ignore our stomp endpoints since they are protected using Stomp headers
.ignoringAntMatchers("/chat/**")
.and()
.headers()
// allow same origin to frame our site to support iframe SockJS
.frameOptions().sameOrigin()
.and()
.authorizeRequests()
...

If we are using XML based configuration, we can use the csrf@request-matcher-ref. For example:
<http ...>
<csrf request-matcher-ref="csrfMatcher"/>
<headers>
<frame-options policy="SAMEORIGIN"/>
</headers>
...
</http>
<b:bean id="csrfMatcher"
class="AndRequestMatcher">
<b:constructor-arg value="#{T(org.springframework.security.web.csrf.CsrfFilter).DEFAULT_MATCHER}"/>
<b:constructor-arg>
<b:bean class="org.springframework.security.web.util.matcher.NegatedRequestMatcher">
<b:bean class="org.springframework.security.web.util.matcher.AntPathRequestMatcher">
<b:constructor-arg value="/chat/**"/>
</b:bean>
</b:bean>
</b:constructor-arg>
</b:bean>

4.0.2.RELEASE

Spring Security

122

Part VI. Authorization

The advanced authorization capabilities within Spring Security represent one of the most compelling
reasons for its popularity. Irrespective of how you choose to authenticate - whether using a Spring
Security-provided mechanism and provider, or integrating with a container or other non-Spring Security
authentication authority - you will find the authorization services can be used within your application in
a consistent and simple way.
In this part well explore the different AbstractSecurityInterceptor implementations, which were
introduced in Part I. We then move on to explore how to fine-tune authorization through use of domain
access control lists.

Spring Security Reference

21. Authorization Architecture

21.1 Authorities
As we saw in the technical overview, all Authentication implementations store a list of
GrantedAuthority objects. These represent the authorities that have been granted to the
principal. the GrantedAuthority objects are inserted into the Authentication object by the
AuthenticationManager and are later read by AccessDecisionManager s when making
authorization decisions.
GrantedAuthority is an interface with only one method:
String getAuthority();

This method allows AccessDecisionManager s to obtain a precise String representation of the

GrantedAuthority. By returning a representation as a String, a GrantedAuthority can be
easily "read" by most AccessDecisionManager s. If a GrantedAuthority cannot be precisely
represented as a String, the GrantedAuthority is considered "complex" and getAuthority()
must return null.
An example of a "complex" GrantedAuthority would be an implementation that stores a list of
operations and authority thresholds that apply to different customer account numbers. Representing
this complex GrantedAuthority as a String would be quite difficult, and as a result the
getAuthority() method should return null. This will indicate to any AccessDecisionManager
that it will need to specifically support the GrantedAuthority implementation in order to understand
its contents.
Spring
Security
includes
one
concrete
GrantedAuthority
implementation,
GrantedAuthorityImpl. This allows any user-specified String to be converted into a
GrantedAuthority. All AuthenticationProvider s included with the security architecture use
GrantedAuthorityImpl to populate the Authentication object.

21.2 Pre-Invocation Handling

As weve also seen in the Technical Overview chapter, Spring Security provides interceptors which
control access to secure objects such as method invocations or web requests. A pre-invocation decision
on whether the invocation is allowed to proceed is made by the AccessDecisionManager.

The AccessDecisionManager
The AccessDecisionManager is called by the AbstractSecurityInterceptor and is
responsible for making final access control decisions. the AccessDecisionManager interface
contains three methods:
void decide(Authentication authentication, Object secureObject,
Collection<ConfigAttribute> attrs) throws AccessDeniedException;
boolean supports(ConfigAttribute attribute);
boolean supports(Class clazz);

The AccessDecisionManagers `decide method is passed all the relevant information it needs
in order to make an authorization decision. In particular, passing the secure Object enables those

4.0.2.RELEASE

Spring Security

124

Spring Security Reference

arguments contained in the actual secure object invocation to be inspected. For example, lets assume
the secure object was a`MethodInvocation`. It would be easy to query the MethodInvocation for any
Customer argument, and then implement some sort of security logic in the AccessDecisionManager
to ensure the principal is permitted to operate on that customer. Implementations are expected to throw
an AccessDeniedException if access is denied.
The supports(ConfigAttribute) method is called by the AbstractSecurityInterceptor
at startup time to determine if the AccessDecisionManager can process the passed
ConfigAttribute. The supports(Class) method is called by a security interceptor implementation
to ensure the configured AccessDecisionManager supports the type of secure object that the security
interceptor will present.

Voting-Based AccessDecisionManager Implementations

Whilst users can implement their own AccessDecisionManager to control all aspects of authorization,
Spring Security includes several AccessDecisionManager implementations that are based on voting.
Figure 21.1, Voting Decision Manager illustrates the relevant classes.

Figure 21.1. Voting Decision Manager

Using this approach, a series of AccessDecisionVoter implementations are polled on an
authorization decision. The AccessDecisionManager then decides whether or not to throw an
AccessDeniedException based on its assessment of the votes.
The AccessDecisionVoter interface has three methods:

4.0.2.RELEASE

Spring Security

125

Spring Security Reference

int vote(Authentication authentication, Object object, Collection<ConfigAttribute> attrs);

boolean supports(ConfigAttribute attribute);
boolean supports(Class clazz);

Concrete implementations return an int, with possible values being reflected in the
AccessDecisionVoter static fields ACCESS_ABSTAIN, ACCESS_DENIED and ACCESS_GRANTED. A
voting implementation will return ACCESS_ABSTAIN if it has no opinion on an authorization decision. If
it does have an opinion, it must return either ACCESS_DENIED or ACCESS_GRANTED.
There are three concrete AccessDecisionManager s provided with Spring Security that tally the
votes. the ConsensusBased implementation will grant or deny access based on the consensus of
non-abstain votes. Properties are provided to control behavior in the event of an equality of votes
or if all votes are abstain. The AffirmativeBased implementation will grant access if one or more
ACCESS_GRANTED votes were received (i.e. a deny vote will be ignored, provided there was at least one
grant vote). Like the ConsensusBased implementation, there is a parameter that controls the behavior
if all voters abstain. The UnanimousBased provider expects unanimous ACCESS_GRANTED votes in
order to grant access, ignoring abstains. It will deny access if there is any ACCESS_DENIED vote. Like
the other implementations, there is a parameter that controls the behaviour if all voters abstain.
It is possible to implement a custom AccessDecisionManager that tallies votes differently. For
example, votes from a particular AccessDecisionVoter might receive additional weighting, whilst a
deny vote from a particular voter may have a veto effect.
RoleVoter
The most commonly used AccessDecisionVoter provided with Spring Security is the simple
RoleVoter, which treats configuration attributes as simple role names and votes to grant access if the
user has been assigned that role.
It will vote if any ConfigAttribute begins with the prefix ROLE_. It will vote to grant access if there
is a GrantedAuthority which returns a String representation (via the getAuthority() method)
exactly equal to one or more ConfigAttributes starting with the prefix ROLE_. If there is no exact
match of any ConfigAttribute starting with ROLE_, the RoleVoter will vote to deny access. If no
ConfigAttribute begins with ROLE_, the voter will abstain.
AuthenticatedVoter
Another voter which weve implicitly seen is the AuthenticatedVoter, which can be used to
differentiate between anonymous, fully-authenticated and remember-me authenticated users. Many
sites allow certain limited access under remember-me authentication, but require a user to confirm their
identity by logging in for full access.
When weve used the attribute IS_AUTHENTICATED_ANONYMOUSLY to grant anonymous access, this
attribute was being processed by the AuthenticatedVoter. See the Javadoc for this class for more
information.
Custom Voters
Obviously, you can also implement a custom AccessDecisionVoter and you can put just about any
access-control logic you want in it. It might be specific to your application (business-logic related) or
it might implement some security administration logic. For example, youll find a blog article on the
SpringSource web site which describes how to use a voter to deny access in real-time to users whose
accounts have been suspended.

4.0.2.RELEASE

Spring Security

126

22. Secure Object Implementations

22.1 AOP Alliance (MethodInvocation) Security Interceptor
Prior to Spring Security 2.0, securing MethodInvocation s needed quite a lot of boiler plate
configuration. Now the recommended approach for method security is to use namespace configuration.
This way the method security infrastructure beans are configured automatically for you so you dont
really need to know about the implementation classes. Well just provide a quick overview of the classes
that are involved here.
Method security in enforced using a MethodSecurityInterceptor, which secures
MethodInvocation s. Depending on the configuration approach, an interceptor may be
specific to a single bean or shared between multiple beans. The interceptor uses a
MethodSecurityMetadataSource instance to obtain the configuration attributes that apply to
a particular method invocation. MapBasedMethodSecurityMetadataSource is used to store
configuration attributes keyed by method names (which can be wildcarded) and will be used
internally when the attributes are defined in the application context using the <intercept-methods>
or <protect-point> elements. Other implementations will be used to handle annotation-based
configuration.

Explicit MethodSecurityInterceptor Configuration

You can of course configure a MethodSecurityIterceptor directly in your application context for
use with one of Spring AOPs proxying mechanisms:
<bean id="bankManagerSecurity" class=
"org.springframework.security.access.intercept.aopalliance.MethodSecurityInterceptor">
<property name="authenticationManager" ref="authenticationManager"/>
<property name="accessDecisionManager" ref="accessDecisionManager"/>
<property name="afterInvocationManager" ref="afterInvocationManager"/>
<property name="securityMetadataSource">
<sec:method-security-metadata-source>
<sec:protect method="com.mycompany.BankManager.delete*" access="ROLE_SUPERVISOR"/>
<sec:protect method="com.mycompany.BankManager.getBalance" access="ROLE_TELLER,ROLE_SUPERVISOR"/>
</sec:method-security-metadata-source>
</property>
</bean>

131

Spring Security Reference

23. Expression-Based Access Control

Spring Security 3.0 introduced the ability to use Spring EL expressions as an authorization mechanism in
addition to the simple use of configuration attributes and access-decision voters which have seen before.
Expression-based access control is built on the same architecture but allows complicated boolean logic
to be encapsulated in a single expression.

23.1 Overview
Spring Security uses Spring EL for expression support and you should look at how that works if you are
interested in understanding the topic in more depth. Expressions are evaluated with a "root object" as
part of the evaluation context. Spring Security uses specific classes for web and method security as the
root object, in order to provide built-in expressions and access to values such as the current principal.

Common Built-In Expressions

The base class for expression root objects is SecurityExpressionRoot. This provides some
common expressions which are available in both web and method security.
Table 23.1. Common built-in expressions
Expression

Description

hasRole([role])

Returns true if the current principal has

the specified role. By default if the supplied
role does not start with 'ROLE_' it will
be added. This can be customized by
modifying the defaultRolePrefix on
DefaultWebSecurityExpressionHandler.

hasAnyRole([role1,role2])

Returns true if the current principal has any

of the supplied roles (given as a commaseparated list of strings). By default if the
supplied role does not start with 'ROLE_' it
will be added. This can be customized by
modifying the defaultRolePrefix on
DefaultWebSecurityExpressionHandler.

hasAuthority([authority])

Returns true if the current principal has the

specified authority.

hasAnyAuthority([authority1,authority2])
Returns true if the current principal has any of
the supplied roles (given as a comma-separated
list of strings)
principal

Allows direct access to the principal object

representing the current user

authentication

Allows direct access to the current

Authentication object obtained from the
SecurityContext

permitAll

Always evaluates to true

4.0.2.RELEASE

Spring Security

132

Spring Security Reference

Expression

Description

denyAll

Always evaluates to false

isAnonymous()

Returns true if the current principal is an

anonymous user

isRememberMe()

Returns true if the current principal is a

remember-me user

isAuthenticated()

Returns true if the user is not anonymous

isFullyAuthenticated()

Returns true if the user is not an anonymous or

a remember-me user

hasPermission(Object target, Object

permission)

Returns true if the user has access to the

provided target for the given permission. For
example, hasPermission(domainObject,
'read')

hasPermission(Object targetId,
String targetType, Object
permission)

Returns true if the user has access to the

provided target for the given permission.
For example, hasPermission(1,
'com.example.domain.Message',
'read')

23.2 Web Security Expressions

To use expressions to secure individual URLs, you would first need to set the use-expressions
attribute in the <http> element to true. Spring Security will then expect the access attributes of the
<intercept-url> elements to contain Spring EL expressions. The expressions should evaluate to a
boolean, defining whether access should be allowed or not. For example:
<http>
<intercept-url pattern="/admin*"
access="hasRole('admin') and hasIpAddress('192.168.1.0/24')"/>
...
</http>

Here we have defined that the "admin" area of an application (defined by the URL pattern) should
only be available to users who have the granted authority "admin" and whose IP address matches
a local subnet. Weve already seen the built-in hasRole expression in the previous section. The
expression hasIpAddress is an additional built-in expression which is specific to web security.
It is defined by the WebSecurityExpressionRoot class, an instance of which is used as the
expression root object when evaluation web-access expressions. This object also directly exposed
the HttpServletRequest object under the name request so you can invoke the request directly
in an expressio If expressions are being used, a WebExpressionVoter will be added to the
AccessDecisionManager which is used by the namespace. So if you arent using the namespace
and want to use expressions, you will have to add one of these to your configuration.

23.3 Method Security Expressions

Method security is a bit more complicated than a simple allow or deny rule. Spring Security 3.0 introduced
some new annotations in order to allow comprehensive support for the use of expressions.

4.0.2.RELEASE

Spring Security

133

Spring Security Reference

@Pre and @Post Annotations

There are four annotations which support expression attributes to allow pre and post-invocation
authorization checks and also to support filtering of submitted collection arguments or return values.
They are @PreAuthorize, @PreFilter, @PostAuthorize and @PostFilter. Their use is enabled
through the global-method-security namespace element:
<global-method-security pre-post-annotations="enabled"/>

Access Control using @PreAuthorize and @PostAuthorize

The most obviously useful annotation is @PreAuthorize which decides whether a method can actually
be invoked or not. For example (from the"Contacts" sample application)
@PreAuthorize("hasRole('USER')")
public void create(Contact contact);

Spring Security Reference

24. Domain Object Security (ACLs)

24.1 Overview
Complex applications often will find the need to define access permissions not simply at a web request
or method invocation level. Instead, security decisions need to comprise both who (Authentication),
where (MethodInvocation) and what (SomeDomainObject). In other words, authorization decisions
also need to consider the actual domain object instance subject of a method invocation.
Imagine youre designing an application for a pet clinic. There will be two main groups of users of your
Spring-based application: staff of the pet clinic, as well as the pet clinics customers. The staff will have
access to all of the data, whilst your customers will only be able to see their own customer records. To
make it a little more interesting, your customers can allow other users to see their customer records,
such as their "puppy preschool" mentor or president of their local "Pony Club". Using Spring Security
as the foundation, you have several approaches that can be used:
Write your business methods to enforce the security. You could consult a collection within
the Customer domain object instance to determine which users have access. By using the
SecurityContextHolder.getContext().getAuthentication(), youll be able to access
the Authentication object.
Write an AccessDecisionVoter to enforce the security from the GrantedAuthority[] s stored
in the Authentication object. This would mean your AuthenticationManager would need
to populate the Authentication with custom GrantedAuthority[]s representing each of the
Customer domain object instances the principal has access to.
Write an AccessDecisionVoter to enforce the security and open the target Customer domain
object directly. This would mean your voter needs access to a DAO that allows it to retrieve the
Customer object. It would then access the Customer objects collection of approved users and make
the appropriate decision.
Each one of these approaches is perfectly legitimate. However, the first couples your authorization
checking to your business code. The main problems with this include the enhanced difficulty of unit
testing and the fact it would be more difficult to reuse the Customer authorization logic elsewhere.
Obtaining the GrantedAuthority[] s from the Authentication object is also fine, but will not
scale to large numbers of Customer s. If a user might be able to access 5,000 Customer s (unlikely in
this case, but imagine if it were a popular vet for a large Pony Club!) the amount of memory consumed
and time required to construct the Authentication object would be undesirable. The final method,
opening the Customer directly from external code, is probably the best of the three. It achieves
separation of concerns, and doesnt misuse memory or CPU cycles, but it is still inefficient in that
both the AccessDecisionVoter and the eventual business method itself will perform a call to the
DAO responsible for retrieving the Customer object. Two accesses per method invocation is clearly
undesirable. In addition, with every approach listed youll need to write your own access control list
(ACL) persistence and business logic from scratch.
Fortunately, there is another alternative, which well talk about below.

24.2 Key Concepts

Spring Securitys ACL services are shipped in the spring-security-acl-xxx.jar. You will need
to add this JAR to your classpath to use Spring Securitys domain object instance security capabilities.

4.0.2.RELEASE

Spring Security

138

Spring Security Reference

Spring Securitys domain object instance security capabilities centre on the concept of an access control
list (ACL). Every domain object instance in your system has its own ACL, and the ACL records details of
who can and cant work with that domain object. With this in mind, Spring Security delivers three main
ACL-related capabilities to your application:
A way of efficiently retrieving ACL entries for all of your domain objects (and modifying those ACLs)
A way of ensuring a given principal is permitted to work with your objects, before methods are called
A way of ensuring a given principal is permitted to work with your objects (or something they return),
after methods are called
As indicated by the first bullet point, one of the main capabilities of the Spring Security ACL module
is providing a high-performance way of retrieving ACLs. This ACL repository capability is extremely
important, because every domain object instance in your system might have several access control
entries, and each ACL might inherit from other ACLs in a tree-like structure (this is supported out-of-thebox by Spring Security, and is very commonly used). Spring Securitys ACL capability has been carefully
designed to provide high performance retrieval of ACLs, together with pluggable caching, deadlockminimizing database updates, independence from ORM frameworks (we use JDBC directly), proper
encapsulation, and transparent database updating.
Given databases are central to the operation of the ACL module, lets explore the four main tables used
by default in the implementation. The tables are presented below in order of size in a typical Spring
Security ACL deployment, with the table with the most rows listed last:
ACL_SID allows us to uniquely identify any principal or authority in the system ("SID" stands for
"security identity"). The only columns are the ID, a textual representation of the SID, and a flag to
indicate whether the textual representation refers to a principal name or a GrantedAuthority.
Thus, there is a single row for each unique principal or GrantedAuthority. When used in the
context of receiving a permission, a SID is generally called a "recipient".
ACL_CLASS allows us to uniquely identify any domain object class in the system. The only columns
are the ID and the Java class name. Thus, there is a single row for each unique Class we wish to
store ACL permissions for.
ACL_OBJECT_IDENTITY stores information for each unique domain object instance in the system.
Columns include the ID, a foreign key to the ACL_CLASS table, a unique identifier so we know which
ACL_CLASS instance were providing information for, the parent, a foreign key to the ACL_SID table
to represent the owner of the domain object instance, and whether we allow ACL entries to inherit
from any parent ACL. We have a single row for every domain object instance were storing ACL
permissions for.
Finally, ACL_ENTRY stores the individual permissions assigned to each recipient. Columns include
a foreign key to the ACL_OBJECT_IDENTITY, the recipient (ie a foreign key to ACL_SID), whether
well be auditing or not, and the integer bit mask that represents the actual permission being granted
or denied. We have a single row for every recipient that receives a permission to work with a domain
object.
As mentioned in the last paragraph, the ACL system uses integer bit masking. Dont worry, you need
not be aware of the finer points of bit shifting to use the ACL system, but suffice to say that we have 32
bits we can switch on or off. Each of these bits represents a permission, and by default the permissions
are read (bit 0), write (bit 1), create (bit 2), delete (bit 3) and administer (bit 4). Its easy to implement
your own Permission instance if you wish to use other permissions, and the remainder of the ACL
framework will operate without knowledge of your extensions.

4.0.2.RELEASE

Spring Security

139

Spring Security Reference

It is important to understand that the number of domain objects in your system has absolutely no
bearing on the fact weve chosen to use integer bit masking. Whilst you have 32 bits available for
permissions, you could have billions of domain object instances (which will mean billions of rows in
ACL_OBJECT_IDENTITY and quite probably ACL_ENTRY). We make this point because weve found
sometimes people mistakenly believe they need a bit for each potential domain object, which is not
the case.
Now that weve provided a basic overview of what the ACL system does, and what it looks like at a table
structure, lets explore the key interfaces. The key interfaces are:
Acl: Every domain object has one and only one Acl object, which internally holds the
AccessControlEntry s as well as knows the owner of the Acl. An Acl does not refer
directly to the domain object, but instead to an ObjectIdentity. The Acl is stored in the
ACL_OBJECT_IDENTITY table.
AccessControlEntry: An Acl holds multiple AccessControlEntry s, which are often
abbreviated as ACEs in the framework. Each ACE refers to a specific tuple of`Permission`, Sid and
Acl. An ACE can also be granting or non-granting and contain audit settings. The ACE is stored in
the ACL_ENTRY table.
Permission: A permission represents a particular immutable bit mask, and offers convenience
functions for bit masking and outputting information. The basic permissions presented above (bits 0
through 4) are contained in the BasePermission class.
Sid: The ACL module needs to refer to principals and GrantedAuthority[] s. A level of
indirection is provided by the Sid interface, which is an abbreviation of "security identity". Common
classes include PrincipalSid (to represent the principal inside an Authentication object) and
GrantedAuthoritySid. The security identity information is stored in the ACL_SID table.
ObjectIdentity: Each domain object is represented internally within the ACL module by an
ObjectIdentity. The default implementation is called ObjectIdentityImpl.
AclService: Retrieves the Acl applicable for a given ObjectIdentity. In the included
implementation (JdbcAclService), retrieval operations are delegated to a LookupStrategy.
The LookupStrategy provides a highly optimized strategy for retrieving ACL information, using
batched retrievals (BasicLookupStrategy) and supporting custom implementations that leverage
materialized views, hierarchical queries and similar performance-centric, non-ANSI SQL capabilities.
MutableAclService: Allows a modified Acl to be presented for persistence. It is not essential to
use this interface if you do not wish.
Please note that our out-of-the-box AclService and related database classes all use ANSI SQL. This
should therefore work with all major databases. At the time of writing, the system had been successfully
tested using Hypersonic SQL, PostgreSQL, Microsoft SQL Server and Oracle.
Two samples ship with Spring Security that demonstrate the ACL module. The first is the Contacts
Sample, and the other is the Document Management System (DMS) Sample. We suggest taking a look
over these for examples.

24.3 Getting Started

To get starting using Spring Securitys ACL capability, you will need to store your ACL information
somewhere. This necessitates the instantiation of a DataSource using Spring. The DataSource is

4.0.2.RELEASE

Spring Security

140

Spring Security Reference

then injected into a JdbcMutableAclService and BasicLookupStrategy instance. The latter

provides high-performance ACL retrieval capabilities, and the former provides mutator capabilities.
Refer to one of the samples that ship with Spring Security for an example configuration. Youll also need
to populate the database with the four ACL-specific tables listed in the last section (refer to the ACL
samples for the appropriate SQL statements).
Once youve created the required schema and instantiated JdbcMutableAclService, youll next
need to ensure your domain model supports interoperability with the Spring Security ACL package.
Hopefully ObjectIdentityImpl will prove sufficient, as it provides a large number of ways in which it
can be used. Most people will have domain objects that contain a public Serializable getId()
method. If the return type is long, or compatible with long (eg an int), you will find you need not give
further consideration to ObjectIdentity issues. Many parts of the ACL module rely on long identifiers.
If youre not using long (or an int, byte etc), there is a very good chance youll need to reimplement a
number of classes. We do not intend to support non-long identifiers in Spring Securitys ACL module,
as longs are already compatible with all database sequences, the most common identifier data type,
and are of sufficient length to accommodate all common usage scenarios.
The following fragment of code shows how to create an Acl, or modify an existing`Acl`:
// Prepare the information we'd like in our access control entry (ACE)
ObjectIdentity oi = new ObjectIdentityImpl(Foo.class, new Long(44));
Sid sid = new PrincipalSid("Samantha");
Permission p = BasePermission.ADMINISTRATION;
// Create or update the relevant ACL
MutableAcl acl = null;
try {
acl = (MutableAcl) aclService.readAclById(oi);
} catch (NotFoundException nfe) {
acl = aclService.createAcl(oi);
}
// Now grant some permissions via an access control entry (ACE)
acl.insertAce(acl.getEntries().length, p, sid, true);
aclService.updateAcl(acl);

In the example above, were retrieving the ACL associated with the "Foo" domain object with identifier
number 44. Were then adding an ACE so that a principal named "Samantha" can "administer" the
object. The code fragment is relatively self-explanatory, except the insertAce method. The first argument
to the insertAce method is determining at what position in the Acl the new entry will be inserted. In the
example above, were just putting the new ACE at the end of the existing ACEs. The final argument is
a boolean indicating whether the ACE is granting or denying. Most of the time it will be granting (true),
but if it is denying (false), the permissions are effectively being blocked.
Spring Security does not provide any special integration to automatically create, update or delete ACLs
as part of your DAO or repository operations. Instead, you will need to write code like shown above for
your individual domain objects. Its worth considering using AOP on your services layer to automatically
integrate the ACL information with your services layer operations. Weve found this quite an effective
approach in the past.
Once youve used the above techniques to store some ACL information in the database, the next step
is to actually use the ACL information as part of authorization decision logic. You have a number of
choices here. You could write your own AccessDecisionVoter or AfterInvocationProvider
that respectively fires before or after a method invocation. Such classes would use AclService
to retrieve the relevant ACL and then call Acl.isGranted(Permission[] permission,
Sid[] sids, boolean administrativeMode) to decide whether permission is granted or

4.0.2.RELEASE

Spring Security

141

Spring Security Reference

denied. Alternately, you could use our AclEntryVoter, AclEntryAfterInvocationProvider

or AclEntryAfterInvocationCollectionFilteringProvider classes. All of these classes
provide a declarative-based approach to evaluating ACL information at runtime, freeing you from
needing to write any code. Please refer to the sample applications to learn how to use these classes.

4.0.2.RELEASE

Spring Security

142

Spring Security Reference

25. Pre-Authentication Scenarios

There are situations where you want to use Spring Security for authorization, but the user has already
been reliably authenticated by some external system prior to accessing the application. We refer to these
situations as "pre-authenticated" scenarios. Examples include X.509, Siteminder and authentication
by the Java EE container in which the application is running. When using pre-authentication, Spring
Security has to
Identify the user making the request.
Obtain the authorities for the user.
The details will depend on the external authentication mechanism. A user might be identified by their
certificate information in the case of X.509, or by an HTTP request header in the case of Siteminder.
If relying on container authentication, the user will be identified by calling the getUserPrincipal()
method on the incoming HTTP request. In some cases, the external mechanism may supply role/
authority information for the user but in others the authorities must be obtained from a separate source,
such as a UserDetailsService.

25.1 Pre-Authentication Framework Classes

Because most pre-authentication mechanisms follow the same pattern, Spring Security has a set
of classes which provide an internal framework for implementing pre-authenticated authentication
providers. This removes duplication and allows new implementations to be added in a structured
fashion, without having to write everything from scratch. You dont need to know about these
classes if you want to use something like X.509 authentication, as it already has a namespace
configuration option which is simpler to use and get started with. If you need to use explicit
bean configuration or are planning on writing your own implementation then an understanding
of how the provided implementations work will be useful. You will find classes under the
org.springframework.security.web.authentication.preauth. We just provide an outline
here so you should consult the Javadoc and source where appropriate.

AbstractPreAuthenticatedProcessingFilter
This class will check the current contents of the security context and, if empty, it will attempt to extract
user information from the HTTP request and submit it to the AuthenticationManager. Subclasses
override the following methods to obtain this information:
protected abstract Object getPreAuthenticatedPrincipal(HttpServletRequest request);
protected abstract Object getPreAuthenticatedCredentials(HttpServletRequest request);

After calling these, the filter will create a PreAuthenticatedAuthenticationToken containing the
returned data and submit it for authentication. By "authentication" here, we really just mean further
processing to perhaps load the users authorities, but the standard Spring Security authentication
architecture is followed.
Like other Spring Security authentication filters, the pre-authentication filter has
an
authenticationDetailsSource
property
which
by
default
will
create
a
WebAuthenticationDetails object to store additional information such as the session-identifier and
originating IP address in the details property of the Authentication object. In cases where user
role information can be obtained from the pre-authentication mechanism, the data is also stored in this

4.0.2.RELEASE

Spring Security

143

Spring Security Reference

property, with the details implementing the GrantedAuthoritiesContainer interface. This enables
the authentication provider to read the authorities which were externally allocated to the user. Well look
at a concrete example next.
J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource
If the filter is configured with an authenticationDetailsSource which is an instance of this
class, the authority information is obtained by calling the isUserInRole(String role) method
for each of a pre-determined set of "mappable roles". The class gets these from a configured
MappableAttributesRetriever. Possible implementations include hard-coding a list in the
application context and reading the role information from the <security-role> information in a
web.xml file. The pre-authentication sample application uses the latter approach.
There is an additional stage where the roles (or attributes) are mapped to Spring Security
GrantedAuthority objects using a configured Attributes2GrantedAuthoritiesMapper. The
default will just add the usual ROLE_ prefix to the names, but it gives you full control over the behaviour.

PreAuthenticatedAuthenticationProvider
The pre-authenticated provider has little more to do than load the UserDetails object for the user.
It does this by delegating to a AuthenticationUserDetailsService. The latter is similar to the
standard UserDetailsService but takes an Authentication object rather than just user name:
public interface AuthenticationUserDetailsService {
UserDetails loadUserDetails(Authentication token) throws UsernameNotFoundException;
}

This interface may have also other uses but with pre-authentication it allows access to the authorities
which were packaged in the Authentication object, as we saw in the previous section. the
PreAuthenticatedGrantedAuthoritiesUserDetailsService class does this. Alternatively, it
may delegate to a standard UserDetailsService via the UserDetailsByNameServiceWrapper
implementation.

Http403ForbiddenEntryPoint
The AuthenticationEntryPoint was discussed in the technical overview chapter. Normally it is
responsible for kick-starting the authentication process for an unauthenticated user (when they try to
access a protected resource), but in the pre-authenticated case this doesnt apply. You would only
configure the ExceptionTranslationFilter with an instance of this class if you arent using preauthentication in combination with other authentication mechanisms. It will be called if the user is
rejected by the AbstractPreAuthenticatedProcessingFilter resulting in a null authentication.
It always returns a 403-forbidden response code if called.

25.2 Concrete Implementations

X.509 authentication is covered in its own chapter. Here well look at some classes which provide support
for other pre-authenticated scenarios.

Request-Header Authentication (Siteminder)

An external authentication system may supply information to the application by setting specific
headers on the HTTP request. A well known example of this is Siteminder, which passes
the username in a header called SM_USER. This mechanism is supported by the class

4.0.2.RELEASE

Spring Security

144

Spring Security Reference

RequestHeaderAuthenticationFilter which simply extracts the username from the header. It

defaults to using the name SM_USER as the header name. See the Javadoc for more details.
Tip
Note that when using a system like this, the framework performs no authentication checks at all
and it is extremely important that the external system is configured properly and protects all access
to the application. If an attacker is able to forge the headers in their original request without this
being detected then they could potentially choose any username they wished.
Siteminder Example Configuration
A typical configuration using this filter would look like this:
<security:http>

<security:custom-filter position="PRE_AUTH_FILTER" ref="siteminderFilter" />
</security:http>

<bean id="siteminderFilter" class="org.springframework.security.web.authentication.preauth.RequestHeaderAuthenticationFilte

<bean id="preauthAuthProvider" class="org.springframework.security.web.authentication.preauth.PreAuthenticatedAuthenticatio

Weve assumed here that the security namespace is being used for configuration. Its also assumed
that you have added a UserDetailsService (called "userDetailsService") to your configuration to
load the users roles.

Java EE Container Authentication

The class J2eePreAuthenticatedProcessingFilter will extract the username from the
userPrincipal property of the HttpServletRequest. Use of this filter would usually
be combined with the use of Java EE roles as described above in the section called
J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource.
There is a sample application in the codebase which uses this approach, so get hold of the code from
subversion and have a look at the application context file if you are interested. The code is in the
samples/preauth directory.

4.0.2.RELEASE

Spring Security

145

Spring Security Reference

26. LDAP Authentication

26.1 Overview
LDAP is often used by organizations as a central repository for user information and as an authentication
service. It can also be used to store the role information for application users.
There are many different scenarios for how an LDAP server may be configured so Spring Securitys
LDAP provider is fully configurable. It uses separate strategy interfaces for authentication and role
retrieval and provides default implementations which can be configured to handle a wide range of
situations.
You should be familiar with LDAP before trying to use it with Spring Security. The following link provides
a good introduction to the concepts involved and a guide to setting up a directory using the free LDAP
server OpenLDAP: http://www.zytrax.com/books/ldap/. Some familiarity with the JNDI APIs used to
access LDAP from Java may also be useful. We dont use any third-party LDAP libraries (Mozilla, JLDAP
etc.) in the LDAP provider, but extensive use is made of Spring LDAP, so some familiarity with that
project may be useful if you plan on adding your own customizations.
When using LDAP authentication, it is important to ensure that you configure LDAP connection pooling
properly. If you are unfamiliar with how to do this, you can refer to the Java LDAP documentation.

26.2 Using LDAP with Spring Security

LDAP authentication in Spring Security can be roughly divided into the following stages.
Obtaining the unique LDAP "Distinguished Name", or DN, from the login name. This will often mean
performing a search in the directory, unless the exact mapping of usernames to DNs is known
in advance. So a user might enter the name "joe" when logging in, but the actual name used to
authenticate to LDAP will be the full DN, such as`uid=joe,ou=users,dc=springsource,dc=com`.
Authenticating the user, either by "binding" as that user or by performing a remote "compare" operation
of the users password against the password attribute in the directory entry for the DN.
Loading the list of authorities for the user.
The exception is when the LDAP directory is just being used to retrieve user information and authenticate
against it locally. This may not be possible as directories are often set up with limited read access for
attributes such as user passwords.
We will look at some configuration scenarios below. For full information on available configuration
options, please consult the security namespace schema (information from which should be available
in your XML editor).

26.3 Configuring an LDAP Server

The first thing you need to do is configure the server against which authentication should take place.
This is done using the <ldap-server> element from the security namespace. This can be configured
to point at an external LDAP server, using the url attribute:
<ldap-server url="ldap://springframework.org:389/dc=springframework,dc=org" />

4.0.2.RELEASE

Spring Security

146

Spring Security Reference

Using an Embedded Test Server

The <ldap-server> element can also be used to create an embedded server, which can be very
useful for testing and demonstrations. In this case you use it without the url attribute:
<ldap-server root="dc=springframework,dc=org"/>

Here weve specified that the root DIT of the directory should be "dc=springframework,dc=org", which
is the default. Used this way, the namespace parser will create an embedded Apache Directory server
and scan the classpath for any LDIF files, which it will attempt to load into the server. You can customize
this behaviour using the ldif attribute, which defines an LDIF resource to be loaded:
<ldap-server ldif="classpath:users.ldif" />

This makes it a lot easier to get up and running with LDAP, since it can be inconvenient to work all the
time with an external server. It also insulates the user from the complex bean configuration needed to
wire up an Apache Directory server. Using plain Spring Beans the configuration would be much more
cluttered. You must have the necessary Apache Directory dependency jars available for your application
to use. These can be obtained from the LDAP sample application.

Using Bind Authentication

This is the most common LDAP authentication scenario.
<ldap-authentication-provider user-dn-pattern="uid={0},ou=people"/>

This simple example would obtain the DN for the user by substituting the user login name in the supplied
pattern and attempting to bind as that user with the login password. This is OK if all your users are
stored under a single node in the directory. If instead you wished to configure an LDAP search filter to
locate the user, you could use the following:
<ldap-authentication-provider user-search-filter="(uid={0})"
user-search-base="ou=people"/>

If used with the server definition above, this would perform a search under the DN
ou=people,dc=springframework,dc=org using the value of the user-search-filter attribute
as a filter. Again the user login name is substituted for the parameter in the filter name, so it will search
for an entry with the uid attribute equal to the user name. If user-search-base isnt supplied, the
search will be performed from the root.

Loading Authorities
How authorities are loaded from groups in the LDAP directory is controlled by the following attributes.
group-search-base. Defines the part of the directory tree under which group searches should be
performed.
group-role-attribute. The attribute which contains the name of the authority defined by the
group entry. Defaults to`cn`
group-search-filter. The filter which is used to search for group membership. The default
2
is`uniqueMember={0}`, corresponding to the groupOfUniqueNames LDAP class . In this case, the
substituted parameter is the full distinguished name of the user. The parameter {1} can be used if
you want to filter on the login name.

4.0.2.RELEASE

Spring Security

147

Spring Security Reference

So if we used the following configuration

<ldap-authentication-provider user-dn-pattern="uid={0},ou=people"
group-search-base="ou=groups" />

and authenticated successfully as user "ben", the subsequent loading of authorities

would perform a search under the directory entry`ou=groups,dc=springframework,dc=org`,
looking
for
entries
which
contain
the
attribute
uniqueMember
with
value
uid=ben,ou=people,dc=springframework,dc=org. By default the authority names will have the
prefix ROLE_ prepended. You can change this using the role-prefix attribute. If you dont want any
prefix, use role-prefix="none". For more information on loading authorities, see the Javadoc for
the DefaultLdapAuthoritiesPopulator class.

26.4 Implementation Classes

The namespace configuration options weve used above are simple to use and much more concise
than using Spring beans explicitly. There are situations when you may need to know how to configure
Spring Security LDAP directly in your application context. You may wish to customize the behaviour of
some of the classes, for example. If youre happy using namespace configuration then you can skip
this section and the next one.
The main LDAP provider class, LdapAuthenticationProvider, doesnt actually do much
itself but delegates the work to two other beans, an LdapAuthenticator and an
LdapAuthoritiesPopulator which are responsible for authenticating the user and retrieving the
users set of GrantedAuthority s respectively.

LdapAuthenticator Implementations
The authenticator is also responsible for retrieving any required user attributes. This is because the
permissions on the attributes may depend on the type of authentication being used. For example, if
binding as the user, it may be necessary to read them with the users own permissions.
There are currently two authentication strategies supplied with Spring Security:
Authentication directly to the LDAP server ("bind" authentication).
Password comparison, where the password supplied by the user is compared with the one stored in
the repository. This can either be done by retrieving the value of the password attribute and checking
it locally or by performing an LDAP "compare" operation, where the supplied password is passed to
the server for comparison and the real password value is never retrieved.
Common Functionality
Before it is possible to authenticate a user (by either strategy), the distinguished name (DN) has to be
obtained from the login name supplied to the application. This can be done either by simple patternmatching (by setting the setUserDnPatterns array property) or by setting the userSearch property.
For the DN pattern-matching approach, a standard Java pattern format is used, and the login name
will be substituted for the parameter {0}. The pattern should be relative to the DN that the configured
SpringSecurityContextSource will bind to (see the section on connecting to the LDAP server
for more information on this). For example, if you are using an LDAP server with the URL`ldap://
monkeymachine.co.uk/dc=springframework,dc=org`, and have a pattern uid={0},ou=greatapes,
then a login name of "gorilla" will map to a DN`uid=gorilla,ou=greatapes,dc=springframework,dc=org`.
Each configured DN pattern will be tried in turn until a match is found. For information on using a search,

4.0.2.RELEASE

Spring Security

148

Spring Security Reference

see the section on search objects below. A combination of the two approaches can also be used - the
patterns will be checked first and if no matching DN is found, the search will be used.
BindAuthenticator
The
class
BindAuthenticator
in
the
package
org.springframework.security.ldap.authentication implements the bind authentication
strategy. It simply attempts to bind as the user.
PasswordComparisonAuthenticator
The class PasswordComparisonAuthenticator
authentication strategy.

implements

the

password

comparison

Connecting to the LDAP Server

The beans discussed above have to be able to connect to the server. They both have
to be supplied with a SpringSecurityContextSource which is an extension of Spring
LDAPs ContextSource. Unless you have special requirements, you will usually configure a
DefaultSpringSecurityContextSource bean, which can be configured with the URL of your
LDAP server and optionally with the username and password of a "manager" user which will be used
by default when binding to the server (instead of binding anonymously). For more information read the
Javadoc for this class and for Spring LDAPs AbstractContextSource.

Spring Security

151

Spring Security Reference

can also inject a GrantedAuthoritiesMapper into the provider instance to control the authorities
which end up in the Authentication object.
Active Directory Error Codes
By default, a failed result will cause a standard Spring Security BadCredentialsException. If you
set the property convertSubErrorCodesToExceptions to true, the exception messages will be
parsed to attempt to extract the Active Directory-specific error code and raise a more specific exception.
Check the class Javadoc for more information.

4.0.2.RELEASE

Spring Security

152

Spring Security Reference

27. JSP Tag Libraries

Spring Security has its own taglib which provides basic support for accessing security information and
applying security constraints in JSPs.

27.1 Declaring the Taglib

To use any of the tags, you must have the security taglib declared in your JSP:
<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>

27.2 The authorize Tag

This tag is used to determine whether its contents should be evaluated or not. In Spring
1
Security 3.0, it can be used in two ways . The first approach uses a web-security expression,
specified in the access attribute of the tag. The expression evaluation will be delegated to
the SecurityExpressionHandler<FilterInvocation> defined in the application context (you
should have web expressions enabled in your <http> namespace configuration to make sure this
service is available). So, for example, you might have
<sec:authorize access="hasRole('supervisor')">
This content will only be visible to users who have the "supervisor" authority in their list
of <tt>GrantedAuthority</tt>s.
</sec:authorize>

When used in conjuction with Spring Securitys PermissionEvaluator, the tag can also be used to check
permissions. For example:
<sec:authorize access="hasPermission(#domain,'read') or hasPermission(#domain,'write')">
This content will only be visible to users who have read or write permission to the Object found as a
request attribute named "domain".
</sec:authorize>

A common requirement is to only show a particular link, if the user is actually allowed to click it. How can
we determine in advance whether something will be allowed? This tag can also operate in an alternative
mode which allows you to define a particular URL as an attribute. If the user is allowed to invoke that
URL, then the tag body will be evaluated, otherwise it will be skipped. So you might have something like
<sec:authorize url="/admin">
This content will only be visible to users who are authorized to send requests to the "/admin" URL.
</sec:authorize>

To use this tag there must also be an instance of WebInvocationPrivilegeEvaluator in your

application context. If you are using the namespace, one will automatically be registered. This is an
instance of DefaultWebInvocationPrivilegeEvaluator, which creates a dummy web request
for the supplied URL and invokes the security interceptor to see whether the request would succeed
or fail. This allows you to delegate to the access-control setup you defined using intercept-url
declarations within the <http> namespace configuration and saves having to duplicate the information
1

The legacy options from Spring Security 2.0 are also supported, but discouraged.

4.0.2.RELEASE

Spring Security

153

Spring Security Reference

(such as the required roles) within your JSPs. This approach can also be combined with a method
attribute, supplying the HTTP method, for a more specific match.
The boolean result of evaluating the tag (whether it grants or denies access) can be stored in a page
context scope variable by setting the var attribute to the variable name, avoiding the need for duplicating
and re-evaluating the condition at other points in the page.

Disabling Tag Authorization for Testing

Hiding a link in a page for unauthorized users doesnt prevent them from accessing the URL. They
could just type it into their browser directly, for example. As part of your testing process, you may
want to reveal the hidden areas in order to check that links really are secured at the back end. If
you set the system property spring.security.disableUISecurity to true, the authorize
tag will still run but will not hide its contents. By default it will also surround the content with <span
class="securityHiddenUI"></span> tags. This allows you to display "hidden" content with a
particular CSS style such as a different background colour. Try running the "tutorial" sample application
with this property enabled, for example.
You
can
also
set
the
properties
spring.security.securedUIPrefix
and
spring.security.securedUISuffix if you want to change surrounding text from the default span
tags (or use empty strings to remove it completely).

27.3 The authentication Tag

This tag allows access to the current Authentication object stored in the security context. It
renders a property of the object directly in the JSP. So, for example, if the principal property
of the Authentication is an instance of Spring Securitys UserDetails object, then using
<sec:authentication property="principal.username" /> will render the name of the
current user.
Of course, it isnt necessary to use JSP tags for this kind of thing and some people prefer to keep as
little logic as possible in the view. You can access the Authentication object in your MVC controller
(by calling SecurityContextHolder.getContext().getAuthentication()) and add the data
directly to your model for rendering by the view.

27.4 The accesscontrollist Tag

This tag is only valid when used with Spring Securitys ACL module. It checks a comma-separated list
of required permissions for a specified domain object. If the current user has all of those permissions,
then the tag body will be evaluated. If they dont, it will be skipped. An example might be
Caution
In general this tag should be considered deprecated. Instead use the Section 27.2, The authorize
Tag.
<sec:accesscontrollist hasPermission="1,2" domainObject="${someObject}">
This will be shown if the user has all of the permissions represented by the values "1" or "2" on the
given object.
</sec:accesscontrollist>

4.0.2.RELEASE

Spring Security

154

Spring Security Reference

The permissions are passed to the PermissionFactory defined in the application context, converting
them to ACL Permission instances, so they may be any format which is supported by the factory - they
dont have to be integers, they could be strings like READ or WRITE. If no PermissionFactory is found,
an instance of DefaultPermissionFactory will be used. The AclService from the application
context will be used to load the Acl instance for the supplied object. The Acl will be invoked with the
required permissions to check if all of them are granted.
This tag also supports the var attribute, in the same way as the authorize tag.

157

Spring Security Reference

JaasGrantedAuthority (which implements Spring Securitys GrantedAuthority interface)

containing the authority string and the JAAS principal that the AuthorityGranter was passed.
The AbstractJaasAuthenticationProvider obtains the JAAS principals by firstly successfully
authenticating the users credentials using the JAAS LoginModule, and then accessing the
LoginContext it returns. A call to LoginContext.getSubject().getPrincipals() is
made, with each resulting principal passed to each AuthorityGranter defined against the
AbstractJaasAuthenticationProvider.setAuthorityGranters(List) property.
Spring Security does not include any production AuthorityGranter s given that every JAAS principal
has an implementation-specific meaning. However, there is a TestAuthorityGranter in the unit
tests that demonstrates a simple AuthorityGranter implementation.

28.3 DefaultJaasAuthenticationProvider
The DefaultJaasAuthenticationProvider allows a JAAS Configuration object to be
injected into it as a dependency. It then creates a LoginContext using the injected JAAS
Configuration. This means that DefaultJaasAuthenticationProvider is not bound any
particular implementation of Configuration as JaasAuthenticationProvider is.

InMemoryConfiguration
In order to make it easy to inject a Configuration into DefaultJaasAuthenticationProvider, a
default in memory implementation named InMemoryConfiguration is provided. The implementation
constructor accepts a Map where each key represents a login configuration name and the value
represents an Array of AppConfigurationEntry s. InMemoryConfiguration also supports a
default Array of AppConfigurationEntry objects that will be used if no mapping is found within the
provided Map. For details, refer to the class level javadoc of InMemoryConfiguration.

Spring Security Reference

29. CAS Authentication

29.1 Overview
JA-SIG produces an enterprise-wide single sign on system known as CAS. Unlike other initiatives,
JA-SIGs Central Authentication Service is open source, widely used, simple to understand, platform
independent, and supports proxy capabilities. Spring Security fully supports CAS, and provides an easy
migration path from single-application deployments of Spring Security through to multiple-application
deployments secured by an enterprise-wide CAS server.
You can learn more about CAS at http://www.ja-sig.org/cas. You will also need to visit this site to
download the CAS Server files.

29.2 How CAS Works

Whilst the CAS web site contains documents that detail the architecture of CAS, we present the general
overview again here within the context of Spring Security. Spring Security 3.x supports CAS 3. At the
time of writing, the CAS server was at version 3.4.
Somewhere in your enterprise you will need to setup a CAS server. The CAS server is simply a standard
WAR file, so there isnt anything difficult about setting up your server. Inside the WAR file you will
customise the login and other single sign on pages displayed to users.
When deploying a CAS 3.4 server, you will also need to specify an AuthenticationHandler
in the deployerConfigContext.xml included with CAS. The AuthenticationHandler has
a simple method that returns a boolean as to whether a given set of Credentials is valid.
Your AuthenticationHandler implementation will need to link into some type of backend
authentication repository, such as an LDAP server or database. CAS itself includes numerous
AuthenticationHandler s out of the box to assist with this. When you download and deploy the
server war file, it is set up to successfully authenticate users who enter a password matching their
username, which is useful for testing.
Apart from the CAS server itself, the other key players are of course the secure web applications
deployed throughout your enterprise. These web applications are known as "services". There are three
types of services. Those that authenticate service tickets, those that can obtain proxy tickets, and those
that authenticate proxy tickets. Authenticating a proxy ticket differs because the list of proxies must be
validated and often times a proxy ticket can be reused.

Spring Security and CAS Interaction Sequence

The basic interaction between a web browser, CAS server and a Spring Security-secured service is
as follows:
The web user is browsing the services public pages. CAS or Spring Security is not involved.
The user eventually requests a page that is either secure or one of the beans it uses is secure.
Spring Securitys ExceptionTranslationFilter will detect the AccessDeniedException or
AuthenticationException.
Because
the
users
Authentication
object
(or
lack
thereof)
caused
an
AuthenticationException, the ExceptionTranslationFilter will call the configured

4.0.2.RELEASE

Spring Security

161

Spring Security Reference

AuthenticationEntryPoint. If using CAS, this will be the CasAuthenticationEntryPoint

class.
The CasAuthenticationEntryPoint will redirect the users browser to the CAS
server. It will also indicate a service parameter, which is the callback URL
for the Spring Security service (your application). For example, the URL to which
the browser is redirected might be https://my.company.com/cas/login?service=https%3A%2F
%2Fserver3.company.com%2Fwebapp%2Flogin/cas.
After the users browser redirects to CAS, they will be prompted for their username and password.
If the user presents a session cookie which indicates theyve previously logged on, they will not be
prompted to login again (there is an exception to this procedure, which well cover later). CAS will
use the PasswordHandler (or AuthenticationHandler if using CAS 3.0) discussed above to
decide whether the username and password is valid.
Upon successful login, CAS will redirect the users browser back to the original service. It will also
include a ticket parameter, which is an opaque string representing the "service ticket". Continuing
our earlier example, the URL the browser is redirected to might be https://server3.company.com/
webapp/login/cas?ticket=ST-0-ER94xMJmn6pha35CQRoZ.
Back in the service web application, the CasAuthenticationFilter is always
listening
for
requests
to
/login/cas
(this
is
configurable,
but
well
use
the
defaults
in
this
introduction).
The
processing
filter
will
construct
a
UsernamePasswordAuthenticationToken representing the service ticket. The principal will be
equal to CasAuthenticationFilter.CAS_STATEFUL_IDENTIFIER, whilst the credentials will
be the service ticket opaque value. This authentication request will then be handed to the configured
AuthenticationManager.
The AuthenticationManager implementation will be the ProviderManager, which is in
turn configured with the CasAuthenticationProvider. The CasAuthenticationProvider
only responds to UsernamePasswordAuthenticationToken s containing the CASspecific principal (such as CasAuthenticationFilter.CAS_STATEFUL_IDENTIFIER) and
CasAuthenticationToken s (discussed later).
CasAuthenticationProvider will validate the service ticket using a TicketValidator
implementation. This will typically be a Cas20ServiceTicketValidator which is one of the
classes included in the CAS client library. In the event the application needs to validate proxy tickets,
the Cas20ProxyTicketValidator is used. The TicketValidator makes an HTTPS request to
the CAS server in order to validate the service ticket. It may also include a proxy callback URL, which
is included in this example: https://my.company.com/cas/proxyValidate?service=https%3A%2F
%2Fserver3.company.com%2Fwebapp%2Flogin/cas&ticket=ST-0ER94xMJmn6pha35CQRoZ&pgtUrl=https://server3.company.com/webapp/login/cas/proxyreceptor.
Back on the CAS server, the validation request will be received. If the presented service ticket matches
the service URL the ticket was issued to, CAS will provide an affirmative response in XML indicating
the username. If any proxy was involved in the authentication (discussed below), the list of proxies
is also included in the XML response.
[OPTIONAL] If the request to the CAS validation service included the proxy callback URL (in the
pgtUrl parameter), CAS will include a pgtIou string in the XML response. This pgtIou represents
a proxy-granting ticket IOU. The CAS server will then create its own HTTPS connection back to
the pgtUrl. This is to mutually authenticate the CAS server and the claimed service URL. The

4.0.2.RELEASE

Spring Security

162

Spring Security Reference

HTTPS connection will be used to send a proxy granting ticket to the original web application.
For example, https://server3.company.com/webapp/login/cas/proxyreceptor?pgtIou=PGTIOU-0R0zlgrl4pdAQwBvJWO3vnNpevwqStbSGcq3vKB2SqSFFRnjPHt&pgtId=PGT-1si9YkkHLrtACBo64rmsi3v2nf7cpCResXg5MpESZFArbaZiOKH.
The Cas20TicketValidator will parse the XML received from the CAS server. It will return to the
CasAuthenticationProvider a TicketResponse, which includes the username (mandatory),
proxy list (if any were involved), and proxy-granting ticket IOU (if the proxy callback was requested).
Next CasAuthenticationProvider will call a configured CasProxyDecider. The
CasProxyDecider indicates whether the proxy list in the TicketResponse is acceptable to
the service. Several implementations are provided with Spring Security: RejectProxyTickets,
AcceptAnyCasProxy and NamedCasProxyDecider. These names are largely self-explanatory,
except NamedCasProxyDecider which allows a List of trusted proxies to be provided.
CasAuthenticationProvider will next request a AuthenticationUserDetailsService to
load the GrantedAuthority objects that apply to the user contained in the Assertion.
If
there
were
no
problems,
CasAuthenticationProvider
constructs
a
CasAuthenticationToken including the details contained in the TicketResponse and the
`GrantedAuthority`s.
Control then returns to CasAuthenticationFilter,
CasAuthenticationToken in the security context.

which

places

the

created

The users browser is redirected to the original page that caused the AuthenticationException
(or a custom destination depending on the configuration).
Its good that youre still here! Lets now look at how this is configured

29.3 Configuration of CAS Client

The web application side of CAS is made easy due to Spring Security. It is assumed you already know
the basics of using Spring Security, so these are not covered again below. Well assume a namespace
based configuration is being used and add in the CAS beans as required. Each section builds upon the
previous section. A fullCAS sample application can be found in the Spring Security Samples.

Service Ticket Authentication

This section describes how to setup Spring Security to authenticate Service Tickets. Often times this is
all a web application requires. You will need to add a ServiceProperties bean to your application
context. This represents your CAS service:
<bean id="serviceProperties"
class="org.springframework.security.cas.ServiceProperties">
<property name="service"
value="https://localhost:8443/cas-sample/login/cas"/>
<property name="sendRenew" value="false"/>
</bean>

The service must equal a URL that will be monitored by the CasAuthenticationFilter. The
sendRenew defaults to false, but should be set to true if your application is particularly sensitive. What
this parameter does is tell the CAS login service that a single sign on login is unacceptable. Instead, the
user will need to re-enter their username and password in order to gain access to the service.

4.0.2.RELEASE

Spring Security

163

Spring Security Reference

The following beans should be configured to commence the CAS authentication process (assuming
youre using a namespace configuration):
<security:http entry-point-ref="casEntryPoint">
...
<security:custom-filter position="CAS_FILTER" ref="casFilter" />
</security:http>
<bean id="casFilter"
class="org.springframework.security.cas.web.CasAuthenticationFilter">
<property name="authenticationManager" ref="authenticationManager"/>
</bean>
<bean id="casEntryPoint"
class="org.springframework.security.cas.web.CasAuthenticationEntryPoint">
<property name="loginUrl" value="https://localhost:9443/cas/login"/>
<property name="serviceProperties" ref="serviceProperties"/>
</bean>

For
CAS
to
operate,
the
ExceptionTranslationFilter
must
have
its
authenticationEntryPoint property set to the CasAuthenticationEntryPoint bean.
This can easily be done using entry-point-ref as is done in the example above. The
CasAuthenticationEntryPoint must refer to the ServiceProperties bean (discussed above),
which provides the URL to the enterprises CAS login server. This is where the users browser will be
redirected.
The
CasAuthenticationFilter
has
very
similar
properties
to
the
UsernamePasswordAuthenticationFilter (used for form-based logins). You can use these
properties to customize things like behavior for authentication success and failure.
Next you need to add a CasAuthenticationProvider and its collaborators:
<security:authentication-manager alias="authenticationManager">
<security:authentication-provider ref="casAuthenticationProvider" />
</security:authentication-manager>
<bean id="casAuthenticationProvider"
class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
<property name="authenticationUserDetailsService">
<bean class="org.springframework.security.core.userdetails.UserDetailsByNameServiceWrapper">
<constructor-arg ref="userService" />
</bean>
</property>
<property name="serviceProperties" ref="serviceProperties" />
<property name="ticketValidator">
<bean class="org.jasig.cas.client.validation.Cas20ServiceTicketValidator">
<constructor-arg index="0" value="https://localhost:9443/cas" />
</bean>
</property>
<property name="key" value="an_id_for_this_auth_provider_only"/>
</bean>
<security:user-service id="userService">
<security:user name="joe" password="joe" authorities="ROLE_USER" />
...
</security:user-service>

The CasAuthenticationProvider uses a UserDetailsService instance to load the authorities

for a user, once they have been authenticated by CAS. Weve shown a simple in-memory setup here.
Note that the CasAuthenticationProvider does not actually use the password for authentication,
but it does use the authorities.
The beans are all reasonably self-explanatory if you refer back to the How CAS Works section.

4.0.2.RELEASE

Spring Security

164

Spring Security Reference

This completes the most basic configuration for CAS. If you havent made any mistakes, your web
application should happily work within the framework of CAS single sign on. No other parts of Spring
Security need to be concerned about the fact CAS handled authentication. In the following sections we
will discuss some (optional) more advanced configurations.

Single Logout
The CAS protocol supports Single Logout and can be easily added to your Spring Security configuration.
Below are updates to the Spring Security configuration that handle Single Logout
<security:http entry-point-ref="casEntryPoint">
...
<security:logout logout-success-url="/cas-logout.jsp"/>
<security:custom-filter ref="requestSingleLogoutFilter" before="LOGOUT_FILTER"/>
<security:custom-filter ref="singleLogoutFilter" before="CAS_FILTER"/>
</security:http>

<bean id="singleLogoutFilter" class="org.jasig.cas.client.session.SingleSignOutFilter"/>

<bean id="requestSingleLogoutFilter"
class="org.springframework.security.web.authentication.logout.LogoutFilter">
<constructor-arg value="https://localhost:9443/cas/logout"/>
<constructor-arg>
<bean class=
"org.springframework.security.web.authentication.logout.SecurityContextLogoutHandler"/>
</constructor-arg>
<property name="filterProcessesUrl" value="/logout/cas"/>
</bean>

The logout element logs the user out of the local application, but does not terminate the
session with the CAS server or any other applications that have been logged into. The
requestSingleLogoutFilter filter will allow the url of /spring_security_cas_logout to be
requested to redirect the application to the configured CAS Server logout url. Then the CAS Server will
send a Single Logout request to all the services that were signed into. The singleLogoutFilter
handles the Single Logout request by looking up the HttpSession in a static Map and then invalidating
it.
It might be confusing why both the logout element and the singleLogoutFilter are needed. It
is considered best practice to logout locally first since the SingleSignOutFilter just stores the
HttpSession in a static Map in order to call invalidate on it. With the configuration above, the flow of
logout would be:
The user requests /logout which would log the user out of the local application and send the user
to the logout success page.
The logout success page, /cas-logout.jsp, should instruct the user to click a link pointing to /
logout/cas in order to logout out of all applications.
When the user clicks the link, the user is redirected to the CAS single logout URL (https://
localhost:9443/cas/logout).
On the CAS Server side, the CAS single logout URL then submits single logout requests to all the
CAS Services. On the CAS Service side, JASIGs SingleSignOutFilter processes the logout
request by invaliditing the original session.
The next step is to add the following to your web.xml

4.0.2.RELEASE

Spring Security

165

Spring Security Reference

<filter>
<filter-name>characterEncodingFilter</filter-name>
<filter-class>
org.springframework.web.filter.CharacterEncodingFilter
</filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>characterEncodingFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<listener>
<listener-class>
org.jasig.cas.client.session.SingleSignOutHttpSessionListener
</listener-class>
</listener>

When using the SingleSignOutFilter you might encounter some encoding issues. Therefore it is
recommended to add the CharacterEncodingFilter to ensure that the character encoding is
correct when using the SingleSignOutFilter. Again, refer to JASIGs documentation for details. The
SingleSignOutHttpSessionListener ensures that when an HttpSession expires, the mapping
used for single logout is removed.

Authenticating to a Stateless Service with CAS

This section describes how to authenticate to a service using CAS. In other words, this section discusses
how to setup a client that uses a service that authenticates with CAS. The next section describes how
to setup a stateless service to Authenticate using CAS.
Configuring CAS to Obtain Proxy Granting Tickets
In order to authenticate to a stateless service, the application needs to obtain a proxy granting ticket
(PGT). This section describes how to configure Spring Security to obtain a PGT building upon thencasst[Service Ticket Authentication] configuration.
The first step is to include a ProxyGrantingTicketStorage in your Spring Security configuration.
This is used to store PGTs that are obtained by the CasAuthenticationFilter so that they can be
used to obtain proxy tickets. An example configuration is shown below
<!-NOTE: In a real application you should not use an in
memory implementation. You will also want to ensure
to clean up expired tickets by calling ProxyGrantingTicketStorage.cleanup()
-->
<bean id="pgtStorage" class="org.jasig.cas.client.proxy.ProxyGrantingTicketStorageImpl"/>

The next step is to update the CasAuthenticationProvider to be able to obtain proxy tickets.
To do this replace the Cas20ServiceTicketValidator with a Cas20ProxyTicketValidator.
The proxyCallbackUrl should be set to a URL that the application will receive PGTs at. Last, the
configuration should also reference the ProxyGrantingTicketStorage so it can use a PGT to obtain
proxy tickets. You can find an example of the configuration changes that should be made below.

4.0.2.RELEASE

Spring Security

166

Spring Security Reference

The last step is to update the CasAuthenticationFilter to accept PGT and to store them
in the ProxyGrantingTicketStorage. It is important the the proxyReceptorUrl matches the
proxyCallbackUrl of the Cas20ProxyTicketValidator. An example configuration is shown
below.
<bean id="casFilter"
class="org.springframework.security.cas.web.CasAuthenticationFilter">
...
<property name="proxyGrantingTicketStorage" ref="pgtStorage"/>
<property name="proxyReceptorUrl" value="/login/cas/proxyreceptor"/>
</bean>

Calling a Stateless Service Using a Proxy Ticket

Now that Spring Security obtains PGTs, you can use them to create proxy tickets which can be used
to authenticate to a stateless service. The CAS sample application contains a working example in the
ProxyTicketSampleServlet. Example code can be found below:
protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
// NOTE: The CasAuthenticationToken can also be obtained using
// SecurityContextHolder.getContext().getAuthentication()
final CasAuthenticationToken token = (CasAuthenticationToken) request.getUserPrincipal();
// proxyTicket could be reused to make calls to the CAS service even if the
// target url differs
final String proxyTicket = token.getAssertion().getPrincipal().getProxyTicketFor(targetUrl);
// Make a remote call using the proxy ticket
final String serviceUrl = targetUrl+"?ticket="+URLEncoder.encode(proxyTicket, "UTF-8");
String proxyResponse = CommonUtils.getResponseFromServer(serviceUrl, "UTF-8");
...
}

Proxy Ticket Authentication

The CasAuthenticationProvider distinguishes between stateful and stateless clients. A stateful
client is considered any that submits to the filterProcessUrl of the CasAuthenticationFilter.
A stateless client is any that presents an authentication request to CasAuthenticationFilter on
a URL other than the filterProcessUrl.
Because remoting protocols have no way of presenting themselves within the context of an
HttpSession, it isnt possible to rely on the default practice of storing the security context in the session
between requests. Furthermore, because the CAS server invalidates a ticket after it has been validated
by the TicketValidator, presenting the same proxy ticket on subsequent requests will not work.
One obvious option is to not use CAS at all for remoting protocol clients. However, this would eliminate
many of the desirable features of CAS. As a middle-ground, the CasAuthenticationProvider

4.0.2.RELEASE

Spring Security

167

Spring Security Reference

uses a StatelessTicketCache. This is used solely for stateless clients which use a
principal equal to CasAuthenticationFilter.CAS_STATELESS_IDENTIFIER. What happens is
the CasAuthenticationProvider will store the resulting CasAuthenticationToken in the
StatelessTicketCache, keyed on the proxy ticket. Accordingly, remoting protocol clients can
present the same proxy ticket and the CasAuthenticationProvider will not need to contact the
CAS server for validation (aside from the first request). Once authenticated, the proxy ticket could be
used for URLs other than the original target service.
This section builds upon the previous sections to accomodate proxy ticket authentication. The first step
is to specify to authenticate all artifacts as shown below.
<bean id="serviceProperties"
class="org.springframework.security.cas.ServiceProperties">
...
<property name="authenticateAllArtifacts" value="true"/>
</bean>

The next step is to specify serviceProperties and the authenticationDetailsSource

for the CasAuthenticationFilter. The serviceProperties property instructs the
CasAuthenticationFilter to attempt to authenticate all artifacts instead of only ones
present on the filterProcessUrl. The ServiceAuthenticationDetailsSource creates
a ServiceAuthenticationDetails that ensures the current URL, based upon the
HttpServletRequest, is used as the service URL when validating the ticket. The
method for generating the service URL can be customized by injecting a custom
AuthenticationDetailsSource that returns a custom ServiceAuthenticationDetails.
<bean id="casFilter"
class="org.springframework.security.cas.web.CasAuthenticationFilter">
...
<property name="serviceProperties" ref="serviceProperties"/>
<property name="authenticationDetailsSource">
<bean class=
"org.springframework.security.cas.web.authentication.ServiceAuthenticationDetailsSource">
<constructor-arg ref="serviceProperties"/>
</bean>
</property>
</bean>

You will also need to update the CasAuthenticationProvider to handle proxy tickets. To do
this replace the Cas20ServiceTicketValidator with a Cas20ProxyTicketValidator. You will
need to configure the statelessTicketCache and which proxies you want to accept. You can find
an example of the updates required to accept all proxies below.

4.0.2.RELEASE

Spring Security

168

Spring Security Reference

4.0.2.RELEASE

Spring Security

169

Spring Security Reference

30. X.509 Authentication

30.1 Overview
The most common use of X.509 certificate authentication is in verifying the identity of a server when
using SSL, most commonly when using HTTPS from a browser. The browser will automatically check
that the certificate presented by a server has been issued (ie digitally signed) by one of a list of trusted
certificate authorities which it maintains.
You can also use SSL with "mutual authentication"; the server will then request a valid certificate from
the client as part of the SSL handshake. The server will authenticate the client by checking that its
certificate is signed by an acceptable authority. If a valid certificate has been provided, it can be obtained
through the servlet API in an application. Spring Security X.509 module extracts the certificate using a
filter. It maps the certificate to an application user and loads that users set of granted authorities for
use with the standard Spring Security infrastructure.
You should be familiar with using certificates and setting up client authentication for your servlet
container before attempting to use it with Spring Security. Most of the work is in creating and installing
suitable certificates and keys. For example, if youre using Tomcat then read the instructions here http://
tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html. Its important that you get this working before trying
it out with Spring Security

30.2 Adding X.509 Authentication to Your Web Application

Enabling X.509 client authentication is very straightforward. Just add the <x509/> element to your http
security namespace configuration.
<http>
...
<x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/>;
</http>

The element has two optional attributes:

subject-principal-regex. The regular expression used to extract a username from the
certificates subject name. The default value is shown above. This is the username which will be
passed to the UserDetailsService to load the authorities for the user.
user-service-ref. This is the bean Id of the UserDetailsService to be used with X.509. It
isnt needed if there is only one defined in your application context.
The subject-principal-regex should contain a single group. For example the default expression
"CN=(.*?)," matches the common name field. So if the subject name in the certificate is "CN=Jimi
Hendrix, OU=", this will give a user name of "Jimi Hendrix". The matches are case insensitive.
So "emailAddress=(.?)," will match "EMAILADDRESS=jimi@hendrix.org,CN=" giving a user name
"jimi@hendrix.org". If the client presents a certificate and a valid username is successfully extracted,
then there should be a valid Authentication object in the security context. If no certificate is found,
or no corresponding user could be found then the security context will remain empty. This means that
you can easily use X.509 authentication with other options such as a form-based login.

172

Spring Security Reference

generated tokens. The RunAsManagerImpl and RunAsImplAuthenticationProvider is created

in the bean context with the same key:
<bean id="runAsManager"
class="org.springframework.security.access.intercept.RunAsManagerImpl">
<property name="key" value="my_run_as_password"/>
</bean>
<bean id="runAsAuthenticationProvider"
class="org.springframework.security.access.intercept.RunAsImplAuthenticationProvider">
<property name="key" value="my_run_as_password"/>
</bean>

By using the same key, each RunAsUserToken can be validated it was created by an approved
RunAsManagerImpl. The RunAsUserToken is immutable after creation for security reasons

4.0.2.RELEASE

Spring Security

173

Spring Security Reference

32. Spring Security Crypto Module

32.1 Introduction
The Spring Security Crypto module provides support for symmetric encryption, key generation, and
password encoding. The code is distributed as part of the core module but has no dependencies on
any other Spring Security (or Spring) code.

32.2 Encryptors
The Encryptors class provides factory methods for constructing symmetric encryptors. Using this class,
you can create ByteEncryptors to encrypt data in raw byte[] form. You can also construct TextEncryptors
to encrypt text strings. Encryptors are thread safe.

BytesEncryptor
Use the Encryptors.standard factory method to construct a "standard" BytesEncryptor:
Encryptors.standard("password", "salt");

The "standard" encryption method is 256-bit AES using PKCS #5s PBKDF2 (Password-Based Key
Derivation Function #2). This method requires Java 6. The password used to generate the SecretKey
should be kept in a secure place and not be shared. The salt is used to prevent dictionary attacks against
the key in the event your encrypted data is compromised. A 16-byte random initialization vector is also
applied so each encrypted message is unique.
The provided salt should be in hex-encoded String form, be random, and be at least 8 bytes in length.
Such a salt may be generated using a KeyGenerator:
String salt = KeyGenerators.string().generateKey(); // generates a random 8-byte salt that is then hexencoded

TextEncryptor
Use the Encryptors.text factory method to construct a standard TextEncryptor:
Encryptors.text("password", "salt");

A TextEncryptor uses a standard BytesEncryptor to encrypt text data. Encrypted results are returned
as hex-encoded strings for easy storage on the filesystem or in the database.
Use the Encryptors.queryableText factory method to construct a "queryable" TextEncryptor:
Encryptors.queryableText("password", "salt");

The difference between a queryable TextEncryptor and a standard TextEncryptor has to do with
initialization vector (iv) handling. The iv used in a queryable TextEncryptor#encrypt operation is shared,
or constant, and is not randomly generated. This means the same text encrypted multiple times will
always produce the same encryption result. This is less secure, but necessary for encrypted data that
needs to be queried against. An example of queryable encrypted text would be an OAuth apiKey.

4.0.2.RELEASE

Spring Security

174

Spring Security Reference

32.3 Key Generators

The KeyGenerators class provides a number of convenience factory methods for constructing different
types of key generators. Using this class, you can create a BytesKeyGenerator to generate byte[] keys.
You can also construct a StringKeyGenerator to generate string keys. KeyGenerators are thread safe.

BytesKeyGenerator
Use the KeyGenerators.secureRandom factory methods to generate a BytesKeyGenerator backed by
a SecureRandom instance:
KeyGenerator generator = KeyGenerators.secureRandom();
byte[] key = generator.generateKey();

The default key length is 8 bytes. There is also a KeyGenerators.secureRandom variant that provides
control over the key length:
KeyGenerators.secureRandom(16);

Use the KeyGenerators.shared factory method to construct a BytesKeyGenerator that always returns
the same key on every invocation:
KeyGenerators.shared(16);

StringKeyGenerator
Use the KeyGenerators.string factory method to construct a 8-byte, SecureRandom KeyGenerator that
hex-encodes each key as a String:
KeyGenerators.string();

32.4 Password Encoding

The password package of the spring-security-crypto module provides support for encoding passwords.
PasswordEncoder is the central service interface and has the following signature:
public interface PasswordEncoder {
String encode(String rawPassword);
boolean matches(String rawPassword, String encodedPassword);
}

The matches method returns true if the rawPassword, once encoded, equals the encodedPassword.
This method is designed to support password-based authentication schemes.
The BCryptPasswordEncoder implementation uses the widely supported "bcrypt" algorithm to hash
the passwords. Bcrypt uses a random 16 byte salt value and is a deliberately slow algorithm, in order
to hinder password crackers. The amount of work it does can be tuned using the "strength" parameter
which takes values from 4 to 31. The higher the value, the more work has to be done to calculate the
hash. The default value is 10. You can change this value in your deployed system without affecting
existing passwords, as the value is also stored in the encoded hash.
// Create an encoder with strength 16
BCryptPasswordEncoder encoder = new BCryptPasswordEncoder(16);
String result = encoder.encode("myPassword");
assertTrue(encoder.matches("myPassword", result));

4.0.2.RELEASE

Spring Security

175

Spring Security Reference

33. Concurrency Support

Spring Security provides a number of optional integrations with Spring MVC. This section covers the
integration in further detail.

34.1 @EnableWebMvcSecurity
Note
As of Spring Security 4.0, @EnableWebMvcSecurity is deprecated. The replacement is
@EnableWebSecurity which will determine adding the Spring MVC features based upon the
classpath.
To enable Spring Security integration with Spring MVC add the @EnableWebSecurity annotation to
your configuration.
Note
Spring Security provides the configuration using Spring MVCs WebMvcConfigurerAdapter.
This means that if you are using more advanced options, like integrating with
WebMvcConfigurationSupport directly, then you will need to manually provide the Spring
Security configuration.

34.2 @AuthenticationPrincipal
Spring Security provides AuthenticationPrincipalArgumentResolver which can automatically
resolve the current Authentication.getPrincipal() for Spring MVC arguments. By using
Section 34.1, @EnableWebMvcSecurity you will automatically have this added to your Spring MVC
configuration. If you use XML based configuraiton, you must add this yourself.
Once AuthenticationPrincipalArgumentResolver is properly configured, you can be entirely
decoupled from Spring Security in your Spring MVC layer.
Consider a situation where a custom UserDetailsService that returns an Object that implements
UserDetails and your own CustomUser Object. The CustomUser of the currently authenticated
user could be accessed using the following code:
import org.springframework.security.web.bind.annotation.AuthenticationPrincipal;
// ...
@RequestMapping("/messages/inbox")
public ModelAndView findMessagesForUser() {
Authentication authentication =
SecurityContextHolder.getContext().getAuthentication();
CustomUser custom = (CustomUser) authentication == null ? null : authentication.getPrincipal();
// .. find messags for this user and return them ...
}

As of Spring Security 3.2 we can resolve the argument more directly by adding an annotation. For
example:

4.0.2.RELEASE

Spring Security

179

Spring Security Reference

@RequestMapping("/messages/inbox")
public ModelAndView findMessagesForUser(@AuthenticationPrincipal CustomUser customUser) {
// .. find messags for this user and return them ...
}

We can further remove our dependency on Spring Security by making @AuthenticationPrincipal

a meta annotation on our own annotation. Below we demonstrate how we could do this on an annotation
named @CurrentUser.
Note
It is important to realize that in order to remove the dependency on Spring Security, it is the
consuming application that would create @CurrentUser. This step is not strictly required, but
assists in isolating your dependency to Spring Security to a more central location.
@Target({ElementType.PARAMETER, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@AuthenticationPrincipal
public @interface CurrentUser {}

Now that @CurrentUser has been specified, we can use it to signal to resolve our CustomUser of the
currently authenticated user. We have also isolated our dependency on Spring Security to a single file.
@RequestMapping("/messages/inbox")
public ModelAndView findMessagesForUser(@CurrentUser CustomUser customUser) {
// .. find messags for this user and return them ...
}

34.3 Spring MVC Async Integration

Spring Web MVC 3.2+ has excellent support for Asynchronous Request Processing. With no additional
configuration, Spring Security will automatically setup the SecurityContext to the Thread that
executes a Callable returned by your controllers. For example, the following method will automatically
have its Callable executed with the SecurityContext that was available when the Callable was
created:
@RequestMapping(method=RequestMethod.POST)
public Callable<String> processUpload(final MultipartFile file) {
return new Callable<String>() {
public Object call() throws Exception {
// ...
return "someView";
}
};
}

Associating SecurityContext to Callables

More technically speaking, Spring Security integrates with WebAsyncManager. The
SecurityContext that is used to process the Callable is the SecurityContext that exists
on the SecurityContextHolder at the time startCallableProcessing is invoked.
There is no automatic integration with a DeferredResult that is returned by controllers. This is
because DeferredResult is processed by the users and thus there is no way of automatically

4.0.2.RELEASE

Spring Security

180

Spring Security Reference

integrating with it. However, you can still use Concurrency Support to provide transparent integration
with Spring Security.

34.4 Spring MVC and CSRF Integration

Automatic Token Inclusion
Spring Security will automatically include the CSRF Token within forms that use the Spring MVC form
tag. For example, the following JSP:
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:c="http://java.sun.com/jsp/jstl/core"
xmlns:form="http://www.springframework.org/tags/form" version="2.0">
<jsp:directive.page language="java" contentType="text/html" />
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

<c:url var="logoutUrl" value="/logout"/>
<form:form action="${logoutUrl}"
method="post">
<input type="submit"
value="Log out" />
<input type="hidden"
name="${_csrf.parameterName}"
value="${_csrf.token}"/>
</form:form>

</html>
</jsp:root>

Will output HTML that is similar to the following:

<form action="/context/logout" method="post">
<input type="submit" value="Log out"/>
<input type="hidden" name="_csrf" value="f81d4fae-7dec-11d0-a765-00a0c91e6bf6"/>
</form>

Resolving the CsrfToken

Spring Security provides CsrfTokenResolver which can automatically resolve the current
CsrfToken for Spring MVC arguments. By using @EnableWebSecurity you will automatically have
this added to your Spring MVC configuration. If you use XML based configuraiton, you must add this
yourself.
Once CsrfTokenResolver is properly configured, you can expose the CsrfToken to your static
HTML based application.
@RestController
public class CsrfController {
@RequestMapping("/csrf")
public CsrfToken csrf(CsrfToken token) {
return token;
}
}

It is important to keep the CsrfToken a secret from other domains. This means if you are using Cross
Origin Sharing (CORS), you should NOT expose the CsrfToken to any external domains.

4.0.2.RELEASE

Spring Security

181

Part VIII. Spring Data Integration

Spring Security provides Spring Data integration that allows referring to the current user within your
queries. It is not only useful but necessary to include the user in the queries to support paged results
since filtering the results afterwards would not scale.

Spring Security Reference

35. Spring Data & Spring Security Configuration

To use this support, provide a bean of type SecurityEvaluationContextExtension. In Java
Configuration, this would look like:
@Bean
public SecurityEvaluationContextExtension securityEvaluationContextExtension() {
return new SecurityEvaluationContextExtension();
}

In XML Configuration, this would look like:

4.0.2.RELEASE

Spring Security

183

Spring Security Reference

36. Security Expressions within @Query

Now Spring Security can be used within your queries. For example:
@Repository
public interface MessageRepository extends PagingAndSortingRepository<Message,Long> {
@Query("select m from Message m where m.to.id = ?#{ principal?.id }")
Page<Message> findInbox(Pageable pageable);
}

This checks to see if the Authentication.getPrincipal().getId() is equal to the recipient

of the Message. Note that this example assumes you have customized the principal to be an Object
that has an id property. By exposing the SecurityEvaluationContextExtension bean, all of the
Common Security Expressions are available within the Query.

4.0.2.RELEASE

Spring Security

184

Part IX. Appendix

Spring Security Reference

37. Security Database Schema

There are various database schema used by the framework and this appendix provides a single
reference point to them all. You only need to provide the tables for the areas of functonality you require.
DDL statements are given for the HSQLDB database. You can use these as a guideline for defining the
schema for the database you are using.

37.1 User Schema

The standard JDBC implementation of the UserDetailsService (JdbcDaoImpl) requires tables to
load the password, account status (enabled or disabled) and a list of authorities (roles) for the user. You
will need to adjust this schema to match the database dialect you are using.
create table users(
username varchar_ignorecase(50) not null primary key,
password varchar_ignorecase(50) not null,
enabled boolean not null
);
create table authorities (
username varchar_ignorecase(50) not null,
authority varchar_ignorecase(50) not null,
constraint fk_authorities_users foreign key(username) references users(username)
);
create unique index ix_auth_username on authorities (username,authority);

Group Authorities
Spring Security 2.0 introduced support for group authorities in JdbcDaoImpl. The table structure if
groups are enabled is as follows. You will need to adjust this schema to match the database dialect
you are using.
create table groups (
id bigint generated by default as identity(start with 0) primary key,
group_name varchar_ignorecase(50) not null
);
create table group_authorities (
group_id bigint not null,
authority varchar(50) not null,
constraint fk_group_authorities_group foreign key(group_id) references groups(id)
);
create table group_members (
id bigint generated by default as identity(start with 0) primary key,
username varchar(50) not null,
group_id bigint not null,
constraint fk_group_members_group foreign key(group_id) references groups(id)
);

Remember that these tables are only required if you are using the provided JDBC
UserDetailsService implementation. If you write your own or choose to implement
AuthenticationProvider without a UserDetailsService, then you have complete freedom over
how you store the data, as long as the interface contract is satisfied.

4.0.2.RELEASE

Spring Security

186

Spring Security Reference

37.2 Persistent Login (Remember-Me) Schema

This table is used to store data used by the more secure persistent token remember-me implementation.
If you are using JdbcTokenRepositoryImpl either directly or through the namespace, then you will
need this table. Remember to adjust this schema to match the database dialect you are using.
create table persistent_logins (
username varchar(64) not null,
series varchar(64) primary key,
token varchar(64) not null,
last_used timestamp not null
);

37.3 ACL Schema

There are four tables used by the Spring Security ACL implementation.
1. acl_sid stores the security identities recognised by the ACL system. These can be unique principals
or authorities which may apply to multiple principals.
2. acl_class defines the domain object types to which ACLs apply. The class column stores the
Java class name of the object.
3. acl_object_identity stores the object identity definitions of specific domai objects.
4. acl_entry stores the ACL permissions which apply to a specific object identity and security identity.
It is assumed that the database will auto-generate the primary keys for each of the identities. The
JdbcMutableAclService has to be able to retrieve these when it has created a new row in the
acl_sid or acl_class tables. It has two properties which define the SQL needed to retrieve these
values classIdentityQuery and sidIdentityQuery. Both of these default to call identity()
The ACL artifact JAR contains files for creating the ACL schema in HyperSQL (HSQLDB), PostgreSQL,
MySQL/MariaDB, Microsoft SQL Server, and Oracle Database. These schemas are also demonstrated
in the following sections.

HyperSQL
The default schema works with the embedded HSQLDB database that is used in unit tests within the
framework.

4.0.2.RELEASE

Spring Security

187

Spring Security Reference

create table acl_sid(

id bigint generated by default as identity(start with 100) not null primary key,
principal boolean not null,
sid varchar_ignorecase(100) not null,
constraint unique_uk_1 unique(sid,principal)
);
create table acl_class(
id bigint generated by default as identity(start with 100) not null primary key,
class varchar_ignorecase(100) not null,
constraint unique_uk_2 unique(class)
);
create table acl_object_identity(
id bigint generated by default as identity(start with 100) not null primary key,
object_id_class bigint not null,
object_id_identity bigint not null,
parent_object bigint,
owner_sid bigint,
entries_inheriting boolean not null,
constraint unique_uk_3 unique(object_id_class,object_id_identity),
constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id),
constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id),
constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id)
);
create table acl_entry(
id bigint generated by default as identity(start with 100) not null primary key,
acl_object_identity bigint not null,
ace_order int not null,
sid bigint not null,
mask integer not null,
granting boolean not null,
audit_success boolean not null,
audit_failure boolean not null,
constraint unique_uk_4 unique(acl_object_identity,ace_order),
constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id),
constraint foreign_fk_5 foreign key(sid) references acl_sid(id)
);

4.0.2.RELEASE

Spring Security

188

Spring Security Reference

PostgreSQL
create table acl_sid(
id bigserial not null primary key,
principal boolean not null,
sid varchar(100) not null,
constraint unique_uk_1 unique(sid,principal)
);
create table acl_class(
id bigserial not null primary key,
class varchar(100) not null,
constraint unique_uk_2 unique(class)
);
create table acl_object_identity(
id bigserial primary key,
object_id_class bigint not null,
object_id_identity bigint not null,
parent_object bigint,
owner_sid bigint,
entries_inheriting boolean not null,
constraint unique_uk_3 unique(object_id_class,object_id_identity),
constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id),
constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id),
constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id)
);
create table acl_entry(
id bigserial primary key,
acl_object_identity bigint not null,
ace_order int not null,
sid bigint not null,
mask integer not null,
granting boolean not null,
audit_success boolean not null,
audit_failure boolean not null,
constraint unique_uk_4 unique(acl_object_identity,ace_order),
constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id),
constraint foreign_fk_5 foreign key(sid) references acl_sid(id)
);

You will have to set the classIdentityQuery and sidIdentityQuery properties of

JdbcMutableAclService to the following values, respectively:
select currval(pg_get_serial_sequence('acl_class', 'id'))
select currval(pg_get_serial_sequence('acl_sid', 'id'))

4.0.2.RELEASE

Spring Security

189

Spring Security Reference

MySQL and MariaDB

CREATE TABLE acl_sid (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
principal BOOLEAN NOT NULL,
sid VARCHAR(100) NOT NULL,
UNIQUE KEY unique_acl_sid (sid, principal)
) ENGINE=InnoDB;
CREATE TABLE acl_class (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
class VARCHAR(100) NOT NULL,
UNIQUE KEY uk_acl_class (class)
) ENGINE=InnoDB;
CREATE TABLE acl_object_identity (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
object_id_class BIGINT UNSIGNED NOT NULL,
object_id_identity BIGINT NOT NULL,
parent_object BIGINT UNSIGNED,
owner_sid BIGINT UNSIGNED,
entries_inheriting BOOLEAN NOT NULL,
UNIQUE KEY uk_acl_object_identity (object_id_class, object_id_identity),
CONSTRAINT fk_acl_object_identity_parent FOREIGN KEY (parent_object) REFERENCES acl_object_identity
(id),
CONSTRAINT fk_acl_object_identity_class FOREIGN KEY (object_id_class) REFERENCES acl_class (id),
CONSTRAINT fk_acl_object_identity_owner FOREIGN KEY (owner_sid) REFERENCES acl_sid (id)
) ENGINE=InnoDB;
CREATE TABLE acl_entry (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
acl_object_identity BIGINT UNSIGNED NOT NULL,
ace_order INTEGER NOT NULL,
sid BIGINT UNSIGNED NOT NULL,
mask INTEGER UNSIGNED NOT NULL,
granting BOOLEAN NOT NULL,
audit_success BOOLEAN NOT NULL,
audit_failure BOOLEAN NOT NULL,
UNIQUE KEY unique_acl_entry (acl_object_identity, ace_order),
CONSTRAINT fk_acl_entry_object FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity (id),
CONSTRAINT fk_acl_entry_acl FOREIGN KEY (sid) REFERENCES acl_sid (id)
) ENGINE=InnoDB;

38. The Security Namespace

This appendix provides a reference to the elements available in the security namespace and information
on the underlying beans they create (a knowledge of the individual classes and how they work together is
assumed - you can find more information in the project Javadoc and elsewhere in this document). If you
havent used the namespace before, please read the introductory chapter on namespace configuration,
as this is intended as a supplement to the information there. Using a good quality XML editor while
editing a configuration based on the schema is recommended as this will provide contextual information
on which elements and attributes are available as well as comments explaining their purpose. The
namespace is written in RELAX NG Compact format and later converted into an XSD schema. If you
are familiar with this format, you may wish to examine the schema file directly.

38.1 Web Application Security

<debug>
Enables Spring Security debugging infrastructure. This will provide human-readable (multi-line)
debugging information to monitor requests coming into the security filters. This may include sensitive
information, such as request parameters or headers, and should only be used in a development
environment.

<content-type-options> Attributes
disabled Specifies if Content Type Options should be disabled. Default false.
Parent Elements of <content-type-options>
headers

<header>
Add additional headers to the response, both the name and value need to be specified.
<header-attributes> Attributes
header-name The name of the header.
value The value of the header to add.
ref Reference to a custom implementation of the HeaderWriter interface.
Parent Elements of <header>
headers

<anonymous>
Adds
an
AnonymousAuthenticationFilter
AnonymousAuthenticationProvider.
Required
IS_AUTHENTICATED_ANONYMOUSLY attribute.

to
if

the
you

stack
are

and
using

an
the

Parent Elements of <anonymous>

http
<anonymous> Attributes
enabled With the default namespace setup, the anonymous "authentication" facility is automatically
enabled. You can disable it using this property.
granted-authority The granted authority that should be assigned to the anonymous request.
Commonly this is used to assign the anonymous request particular roles, which can subsequently be
used in authorization decisions. If unset, defaults to ROLE_ANONYMOUS.
key The key shared between the provider and filter. This generally does not need to be set. If unset, it
will default to a secure randomly generated value. This means setting this value can improve startup
time when using the anonymous functionality since secure random values can take a while to be
generated.
username The username that should be assigned to the anonymous request. This allows the
principal to be identified, which may be important for logging and auditing. if unset, defaults to
anonymousUser.

<csrf>
This element will add Cross Site Request Forger (CSRF) protection to the application. It also updates
the default RequestCache to only replay "GET" requests upon successful authentication. Additional
information can be found in the Cross Site Request Forgery (CSRF) section of the reference.

4.0.2.RELEASE

Spring Security

199

Spring Security Reference

Parent Elements of <csrf>

http
<csrf> Attributes
disabled Optional attribute that specifies to disable Spring Securitys CSRF protection. The default
is false (CSRF protection is enabled). It is highly recommended to leave CSRF protection enabled.
token-repository-ref
The
CsrfTokenRepository
HttpSessionCsrfTokenRepository.

use.

The

default

request-matcher-ref The RequestMatcher instance to be used to determine if CSRF should be

applied. Default is any HTTP method except "GET", "TRACE", "HEAD", "OPTIONS".

<custom-filter>
This element is used to add a filter to the filter chain. It doesnt create any additional beans but is used
to select a bean of type javax.servlet.Filter which is already defined in the application context
and add that at a particular position in the filter chain maintained by Spring Security. Full details can
be found in the namespace chapter.
Parent Elements of <custom-filter>
http
<custom-filter> Attributes
after The filter immediately after which the custom-filter should be placed in the chain. This feature
will only be needed by advanced users who wish to mix their own filters into the security filter chain
and have some knowledge of the standard Spring Security filters. The filter names map to specific
Spring Security implementation filters.
before The filter immediately before which the custom-filter should be placed in the chain
position The explicit position at which the custom-filter should be placed in the chain. Use if you are
replacing a standard filter.
ref Defines a reference to a Spring bean that implements Filter.

<expression-handler>
Defines the SecurityExpressionHandler instance which will be used if expression-based accesscontrol is enabled. A default implementation (with no ACL support) will be used if not supplied.
Parent Elements of <expression-handler>
global-method-security
http
websocket-message-broker
<expression-handler> Attributes
ref Defines a reference to a Spring bean that implements SecurityExpressionHandler.

4.0.2.RELEASE

Spring Security

200

Spring Security Reference

<form-login>
Used to add an UsernamePasswordAuthenticationFilter to the filter stack and an
LoginUrlAuthenticationEntryPoint to the application context to provide authentication on
demand. This will always take precedence over other namespace-created entry points. If no attributes
16
are supplied, a login page will be generated automatically at the URL "/login" The behaviour can be
customized using the <form-login> Attributes.
Parent Elements of <form-login>
http
<form-login> Attributes
always-use-default-target If set to true, the user will always start at the value given
by default-target-url, regardless of how they arrived at the login page. Maps to the
alwaysUseDefaultTargetUrl property of UsernamePasswordAuthenticationFilter.
Default value is false.
authentication-details-source-ref Reference to an AuthenticationDetailsSource which will
be used by the authentication filter
authentication-failure-handler-ref Can be used as an alternative to authentication-failure-url, giving
you full control over the navigation flow after an authentication failure. The value should be he name
of an AuthenticationFailureHandler bean in the application context.
authentication-failure-url Maps to the authenticationFailureUrl property of
UsernamePasswordAuthenticationFilter. Defines the URL the browser will be redirected to
on login failure. Defaults to /login?error, which will be automatically handled by the automatic
login page generator, re-rendering the login page with an error message.
authentication-success-handler-ref This can be used as an alternative to defaulttarget-url and always-use-default-target, giving you full control over the navigation
flow after a successful authentication. The value should be the name of an
AuthenticationSuccessHandler bean in the application context. By default, an implementation
of SavedRequestAwareAuthenticationSuccessHandler is used and injected with the defaulttarget-url.
default-target-url
Maps
to
the
defaultTargetUrl
property
of
UsernamePasswordAuthenticationFilter. If not set, the default value is "/" (the application
root). A user will be taken to this URL after logging in, provided they were not asked to login while
attempting to access a secured resource, when they will be taken to the originally requested URL.
login-page The URL that should be used to render the login page. Maps to the loginFormUrl
property of the LoginUrlAuthenticationEntryPoint. Defaults to "/login".
login-processing-url
Maps
to
the
filterProcessesUrl
UsernamePasswordAuthenticationFilter. The default value is "/login".

property

password-parameter The name of the request parameter which contains the password. Defaults
to "password".
16

This feature is really just provided for convenience and is not intended for production (where a view technology will have been
chosen and can be used to render a customized login page). The class DefaultLoginPageGeneratingFilter is responsible
for rendering the login page and will provide login forms for both normal form login and/or OpenID if required.

4.0.2.RELEASE

Spring Security

201

Spring Security Reference

username-parameter The name of the request parameter which contains the username. Defaults
to "username".

<http-basic>
Adds a BasicAuthenticationFilter and BasicAuthenticationEntryPoint to the
configuration. The latter will only be used as the configuration entry point if form-based login is not
enabled.
Parent Elements of <http-basic>
http
<http-basic> Attributes
authentication-details-source-ref Reference to an AuthenticationDetailsSource which will
be used by the authentication filter
entry-point-ref Sets the AuthenticationEntryPoint
BasicAuthenticationFilter.

which

used

the

<http-firewall> Element
This is a top-level element which can be used to inject a custom implementation of HttpFirewall into
the FilterChainProxy created by the namespace. The default implementation should be suitable
for most applications.
<http-firewall> Attributes
ref Defines a reference to a Spring bean that implements HttpFirewall.

<intercept-url>
This element is used to define the set of URL patterns that the application is
interested in and to configure how they should be handled. It is used to construct the
FilterInvocationSecurityMetadataSource used by the FilterSecurityInterceptor. It
is also responsible for configuring a ChannelProcessingFilter if particular URLs need to be
accessed by HTTPS, for example. When matching the specified patterns against an incoming request,
the matching is done in the order in which the elements are declared. So the most specific matches
patterns should come first and the most general should come last.
Parent Elements of <intercept-url>
filter-security-metadata-source
http
<intercept-url> Attributes
access
Lists
the
access
attributes
which
will
be
stored
in
the
FilterInvocationSecurityMetadataSource for the defined URL pattern/method
combination. This should be a comma-separated list of the security configuration attributes (such as
role names).
filters Can only take the value "none". This will cause any matching request to bypass the Spring
Security filter chain entirely. None of the rest of the <http> configuration will have any effect on the

4.0.2.RELEASE

Spring Security

202

Spring Security Reference

request and there will be no security context available for its duration. Access to secured methods
during the request will fail.
Note
This property is invalid for filter-security-metadata-source
method The HTTP Method which will be used in combination with the pattern to match an incoming
request. If omitted, any method will match. If an identical pattern is specified with and without a method,
the method-specific match will take precedence.
pattern The pattern which defines the URL path. The content will depend on the request-matcher
attribute from the containing http element, so will default to ant path syntax.
requires-channel Can be "http" or "https" depending on whether a particular URL pattern should
be accessed over HTTP or HTTPS respectively. Alternatively the value "any" can be used when
there is no preference. If this attribute is present on any <intercept-url> element, then a
ChannelProcessingFilter will be added to the filter stack and its additional dependencies added
to the application context.
If a <port-mappings> configuration is added, this will be used to by the SecureChannelProcessor
and InsecureChannelProcessor beans to determine the ports used for redirecting to HTTP/HTTPS.
Note
This property is invalid for filter-security-metadata-source

<jee>
Adds a J2eePreAuthenticatedProcessingFilter to the filter chain to provide integration with container
authentication.
Parent Elements of <jee>
http
<jee> Attributes
mappable-roles A comma-separate list of roles to look for in the incoming HttpServletRequest.
user-service-ref A reference to a user-service (or UserDetailsService bean) Id

<logout>
Adds
a
LogoutFilter
to
the
SecurityContextLogoutHandler.

filter

stack.

This

configured

with

Parent Elements of <logout>

http
<logout> Attributes
delete-cookies A comma-separated list of the names of cookies which should be deleted when the
user logs out.

4.0.2.RELEASE

Spring Security

203

Spring Security Reference

invalidate-session
Maps
to
the
invalidateHttpSession
of
the
SecurityContextLogoutHandler. Defaults to "true", so the session will be invalidated on logout.
logout-success-url The destination URL which the user will be taken to after logging out. Defaults
to <form-login-login-page>/?logout (i.e. /login?logout)
Setting
this
attribute
will
inject
the
SessionManagementFilter
with
a
SimpleRedirectInvalidSessionStrategy configured with the attribute value. When an invalid
session ID is submitted, the strategy will be invoked, redirecting to the configured URL.
logout-url The URL which will cause a logout (i.e. which will be processed by the filter). Defaults
to "/logout".
success-handler-ref May be used to supply an instance of LogoutSuccessHandler which will be
invoked to control the navigation after logging out.

<openid-login>
Similar to <form-login> and has the same attributes. The default value for login-processing-url
is "/login/openid". An OpenIDAuthenticationFilter and OpenIDAuthenticationProvider
will be registered. The latter requires a reference to a UserDetailsService. Again, this can be
specified by id, using the user-service-ref attribute, or will be located automatically in the
application context.
Parent Elements of <openid-login>
http
<openid-login> Attributes
always-use-default-target Whether the user should always be redirected to the default-target-url
after login.
authentication-details-source-ref Reference to an AuthenticationDetailsSource which will be used
by the authentication filter
authentication-failure-handler-ref Reference to an AuthenticationFailureHandler bean which
should be used to handle a failed authentication request. Should not be used in combination with
authentication-failure-url as the implementation should always deal with navigation to the subsequent
destination
authentication-failure-url The URL for the login failure page. If no login failure URL is specified,
Spring Security will automatically create a failure login URL at /login?login_error and a corresponding
filter to render that login failure URL when requested.
authentication-success-handler-ref Reference to an AuthenticationSuccessHandler bean which
should be used to handle a successful authentication request. Should not be used in combination
with default-target-url (or always-use-default-target) as the implementation should always deal with
navigation to the subsequent destination
default-target-url The URL that will be redirected to after successful authentication, if the users
previous action could not be resumed. This generally happens if the user visits a login page without
having first requested a secured operation that triggers authentication. If unspecified, defaults to the
root of the application.

4.0.2.RELEASE

Spring Security

204

Spring Security Reference

login-page The URL for the login page. If no login URL is specified, Spring Security will automatically
create a login URL at /login and a corresponding filter to render that login URL when requested.
login-processing-url The URL that the login form is posted to. If unspecified, it defaults to /login.
password-parameter The name of the request parameter which contains the password. Defaults
to "password".
user-service-ref A reference to a user-service (or UserDetailsService bean) Id
username-parameter The name of the request parameter which contains the username. Defaults
to "username".
Child Elements of <openid-login>
attribute-exchange

<attribute-exchange>
The attribute-exchange element defines the list of attributes which should be requested from
the identity provider. An example can be found in the OpenID Support section of the namespace
configuration chapter. More than one can be used, in which case each must have an identifiermatch attribute, containing a regular expression which is matched against the supplied OpenID
identifier. This allows different attribute lists to be fetched from different providers (Google, Yahoo etc).
Parent Elements of <attribute-exchange>
openid-login
<attribute-exchange> Attributes
identifier-match A regular expression which will be compared against the claimed identity, when
deciding which attribute-exchange configuration to use during authentication.
Child Elements of <attribute-exchange>
openid-attribute

<openid-attribute>
Attributes used when making an OpenID AX Fetch Request
Parent Elements of <openid-attribute>
attribute-exchange
<openid-attribute> Attributes
count Specifies the number of attributes that you wish to get back. For example, return 3 emails.
The default value is 1.
name Specifies the name of the attribute that you wish to get back. For example, email.
required Specifies if this attribute is required to the OP, but does not error out if the OP does not
return the attribute. Default is false.

4.0.2.RELEASE

Spring Security

205

Spring Security Reference

type Specifies the attribute type. For example, http://axschema.org/contact/email. See your OPs
documentation for valid attribute types.

<port-mappings>
By default, an instance of PortMapperImpl will be added to the configuration for use in redirecting
to secure and insecure URLs. This element can optionally be used to override the default mappings
which that class defines. Each child <port-mapping> element defines a pair of HTTP:HTTPS ports.
The default mappings are 80:443 and 8080:8443. An example of overriding these can be found in the
namespace introduction.
Parent Elements of <port-mappings>
http
Child Elements of <port-mappings>
port-mapping

<port-mapping>
Provides a method to map http ports to https ports when forcing a redirect.
Parent Elements of <port-mapping>
port-mappings
<port-mapping> Attributes
http The http port to use.
https The https port to use.

<remember-me>
Adds the RememberMeAuthenticationFilter to the stack. This in turn will be configured with
either a TokenBasedRememberMeServices, a PersistentTokenBasedRememberMeServices
or a user-specified bean implementing RememberMeServices depending on the attribute settings.
Parent Elements of <remember-me>
http
<remember-me> Attributes
authentication-success-handler-ref Sets the authenticationSuccessHandler property on
the RememberMeAuthenticationFilter if custom navigation is required. The value should be
the name of a AuthenticationSuccessHandler bean in the application context.
data-source-ref
A
reference
to
a
DataSource
bean.
If
this
is
set,
PersistentTokenBasedRememberMeServices will be used and configured with a
JdbcTokenRepositoryImpl instance.
remember-me-parameter The name of the request parameter which toggles rememberme authentication. Defaults to "remember-me". Maps to the "parameter" property of
AbstractRememberMeServices.

4.0.2.RELEASE

Spring Security

206

Spring Security Reference

remember-me-cookie The name of cookie which store the token for rememberme authentication. Defaults to "remember-me". Maps to the "cookieName" property of
AbstractRememberMeServices.
key Maps to the "key" property of AbstractRememberMeServices. Should be set to a unique value
18
to ensure that remember-me cookies are only valid within the one application . If this is not set a
secure random value will be generated. Since generating secure random values can take a while,
setting this value explicitly can help improve startup times when using the remember me functionality.
services-alias Exports the internally defined RememberMeServices as a bean alias, allowing it to
be used by other beans in the application context.
services-ref Allows complete control of the RememberMeServices implementation that will be used
by the filter. The value should be the id of a bean in the application context which implements this
interface. Should also implement LogoutHandler if a logout filter is in use.
token-repository-ref Configures a PersistentTokenBasedRememberMeServices but allows
the use of a custom PersistentTokenRepository bean.
token-validity-seconds
Maps
to
the
tokenValiditySeconds
property
of
AbstractRememberMeServices. Specifies the period in seconds for which the remember-me
cookie should be valid. By default it will be valid for 14 days.
use-secure-cookie It is recommended that remember-me cookies are only submitted over HTTPS
and thus should be flagged as "secure". By default, a secure cookie will be used if the connection
over which the login request is made is secure (as it should be). If you set this property to false,
secure cookies will not be used. Setting it to true will always set the secure flag on the cookie. This
attribute maps to the useSecureCookie property of AbstractRememberMeServices.
user-service-ref The remember-me services implementations require access to a
UserDetailsService, so there has to be one defined in the application context. If there is only
one, it will be selected and used automatically by the namespace configuration. If there are multiple
instances, you can specify a bean id explicitly using this attribute.

<request-cache> Element
Sets the RequestCache instance which will be used by the ExceptionTranslationFilter to store
request information before invoking an AuthenticationEntryPoint.
Parent Elements of <request-cache>
http
<request-cache> Attributes
ref Defines a reference to a Spring bean that is a RequestCache.

<session-management>
Session-management related functionality is
SessionManagementFilter to the filter stack.

implemented

the

addition

Parent Elements of <session-management>

http

4.0.2.RELEASE

Spring Security

207

Spring Security Reference

<session-management> Attributes
invalid-session-url Setting this attribute will inject the SessionManagementFilter with a
SimpleRedirectInvalidSessionStrategy configured with the attribute value. When an invalid
session ID is submitted, the strategy will be invoked, redirecting to the configured URL.
session-authentication-error-url Defines the URL of the error page which should be shown when
the SessionAuthenticationStrategy raises an exception. If not set, an unauthorized (401) error code
will be returned to the client. Note that this attribute doesnt apply if the error occurs during a formbased login, where the URL for authentication failure will take precedence.
session-authentication-strategy-ref Allows injection of the SessionAuthenticationStrategy instance
used by the SessionManagementFilter
session-fixation-protection Indicates how session fixation protection will be applied when a user
authenticates. If set to "none", no protection will be applied. "newSession" will create a new
empty session, with only Spring Security-related attributes migrated. "migrateSession" will create
a new session and copy all session attributes to the new session. In Servlet 3.1 (Java EE 7)
and newer containers, specifying "changeSessionId" will keep the existing session and use the
container-supplied session fixation protection (HttpServletRequest#changeSessionId()). Defaults to
"changeSessionId" in Servlet 3.1 and newer containers, "migrateSession" in older containers. Throws
an exception if "changeSessionId" is used in older containers.
If session fixation protection is enabled, the SessionManagementFilter is injected with an
appropriately configured DefaultSessionAuthenticationStrategy. See the Javadoc for this
class for more details.
Child Elements of <session-management>
concurrency-control

<concurrency-control>
Adds support for concurrent session control, allowing limits to be placed on the number
of active sessions a user can have. A ConcurrentSessionFilter will be created,
and a ConcurrentSessionControlAuthenticationStrategy will be used with the
SessionManagementFilter. If a form-login element has been declared, the strategy object
will also be injected into the created authentication filter. An instance of SessionRegistry (a
SessionRegistryImpl instance unless the user wishes to use a custom bean) will be created for
use by the strategy.
Parent Elements of <concurrency-control>
session-management
<concurrency-control> Attributes
error-if-maximum-exceeded If set to "true" a SessionAuthenticationException will be raised
when a user attempts to exceed the maximum allowed number of sessions. The default behaviour
is to expire the original session.
expired-url The URL a user will be redirected to if they attempt to use a session which has been
"expired" by the concurrent session controller because the user has exceeded the number of allowed
sessions and has logged in again elsewhere. Should be set unless exception-if-maximum-

4.0.2.RELEASE

Spring Security

208

Spring Security Reference

exceeded is set. If no value is supplied, an expiry message will just be written directly back to the
response.
max-sessions
Maps
to
the
maximumSessions
ConcurrentSessionControlAuthenticationStrategy.

property

session-registry-alias It can also be useful to have a reference to the internal session registry for
use in your own beans or an admin interface. You can expose the internal bean using the sessionregistry-alias attribute, giving it a name that you can use elsewhere in your configuration.
session-registry-ref The user can supply their own SessionRegistry implementation using the
session-registry-ref attribute. The other concurrent session control beans will be wired up to
use it.

<x509>
Adds support for X.509 authentication. An X509AuthenticationFilter will be added to the stack
and an Http403ForbiddenEntryPoint bean will be created. The latter will only be used if no other
authentication mechanisms are in use (its only functionality is to return an HTTP 403 error code). A
PreAuthenticatedAuthenticationProvider will also be created which delegates the loading of
user authorities to a UserDetailsService.
Parent Elements of <x509>
http
<x509> Attributes
authentication-details-source-ref A reference to an AuthenticationDetailsSource
subject-principal-regex Defines a regular expression which will be used to extract the username
from the certificate (for use with the UserDetailsService).
user-service-ref Allows a specific UserDetailsService to be used with X.509 in the case where
multiple instances are configured. If not set, an attempt will be made to locate a suitable instance
automatically and use that.

<filter-chain-map>
Used to explicitly configure a FilterChainProxy instance with a FilterChainMap
<filter-chain-map> Attributes
request-matcher Defines the strategy use for matching incoming requests. Currently the options are
'ant' (for ant path patterns), 'regex' for regular expressions and 'ciRegex' for case-insensitive regular
expressions.
Child Elements of <filter-chain-map>
filter-chain

<filter-chain>
Used within to define a specific URL pattern and the list of filters which apply to the URLs matching
that pattern. When multiple filter-chain elements are assembled in a list in order to configure a

4.0.2.RELEASE

Spring Security

209

Spring Security Reference

FilterChainProxy, the most specific patterns must be placed at the top of the list, with most general ones
at the bottom.
Parent Elements of <filter-chain>
filter-chain-map
<filter-chain> Attributes
filters A comma separated list of references to Spring beans that implement Filter. The value
"none" means that no Filters should be used for this `FilterChain.
pattern A-pattern that creates RequestMatcher in combination with the request-matcher
request-matcher-ref A reference to a RequestMatcher that will be used to determine if the
Filters from the `filters attribute should be invoked.

<filter-security-metadata-source>
Used to explicitly configure a FilterSecurityMetadataSource bean for use with a FilterSecurityInterceptor.
Usually only needed if you are configuring a FilterChainProxy explicitly, rather than using the<http>
element. The intercept-url elements used should only contain pattern, method and access attributes.
Any others will result in a configuration error.
<filter-security-metadata-source> Attributes
id A bean identifier, used for referring to the bean elsewhere in the context.
lowercase-comparisons Compare after forcing to lower case
request-matcher Defines the strategy use for matching incoming requests. Currently the options are
'ant' (for ant path patterns), 'regex' for regular expressions and 'ciRegex' for case-insensitive regular
expressions.
use-expressions Enables the use of expressions in the 'access' attributes in <intercept-url> elements
rather than the traditional list of configuration attributes. Defaults to 'true'. If enabled, each attribute
should contain a single boolean expression. If the expression evaluates to 'true', access will be
granted.
Child Elements of <filter-security-metadata-source>
intercept-url

38.2 WebSocket Security

Spring Security 4.0+ provides support for authorizing messages. One concrete example of where this
is useful is to provide authorization in WebSocket based applications.

<websocket-message-broker>
The websocket-message-broker element has two different modes. If the websocket-messagebroker@id is not specified, then it will do the following things:
Ensure
that
any
SimpAnnotationMethodMessageHandler
has
the
AuthenticationPrincipalArgumentResolver registered as a custom argument resolver. This allows the
use of @AuthenticationPrincipal to resolve the principal of the current Authentication

4.0.2.RELEASE

Spring Security

210

Spring Security Reference

Ensures that the SecurityContextChannelInterceptor is automatically registered for the

clientInboundChannel. This populates the SecurityContextHolder with the user that is found in the
Message
Ensures that a ChannelSecurityInterceptor is registered with the clientInboundChannel. This allows
authorization rules to be specified for a message.
Ensures that a CsrfChannelInterceptor is registered with the clientInboundChannel. This ensures that
only requests from the original domain are enabled.
Ensures that a CsrfTokenHandshakeInterceptor is registered with WebSocketHttpRequestHandler,
TransportHandlingSockJsService, or DefaultSockJsService. This ensures that the expected
CsrfToken from the HttpServletRequest is copied into the WebSocket Session attributes.
If additional control is necessary, the id can be specified and a ChannelSecurityInterceptor will be
assigned to the specified id. All the wiring with Springs messaging infrastructure can then be done
manually. This is more cumbersome, but provides greater control over the configuration.
<websocket-message-broker> Attributes
id A bean identifier, used for referring to the ChannelSecurityInterceptor bean elsewhere in the
context. If specified, Spring Security requires explicit configuration within Spring Messaging. If not
specified, Spring Security will automatically integrate with the messaging infrastructure as described
in the section called <websocket-message-broker>
same-origin-disabled Disables the requirement for CSRF token to be present in the Stomp headers
(default false). Changing the default is useful if it is necessary to allow other origins to make SockJS
connections.
Child Elements of <websocket-message-broker>
expression-handler
intercept-message

<intercept-message>
Defines an authorization rule for a message.
Parent Elements of <intercept-message>
websocket-message-broker
<intercept-message> Attributes
pattern An ant based pattern that matches on the Message destination. For example, "/" matches
any Message with a destination; "/admin/" matches any Message that has a destination that starts
with "/admin/**".
type The type of message to match on. Valid values are defined in SimpMessageType
(i.e. CONNECT, CONNECT_ACK, HEARTBEAT, MESSAGE, SUBSCRIBE, UNSUBSCRIBE,
DISCONNECT, DISCONNECT_ACK, OTHER).
access The expression used to secure the Message. For example, "denyAll" will deny access
to all of the matching Messages; "permitAll" will grant access to all of the matching Messages;

4.0.2.RELEASE

Spring Security

211

Spring Security Reference

"hasRole('ADMIN') requires the current user to have the role 'ROLE_ADMIN' for the matching
Messages.

38.3 Authentication Services

Before Spring Security 3.0, an AuthenticationManager was automatically registered internally. Now
you must register one explicitly using the <authentication-manager> element. This creates an
instance of Spring Securitys ProviderManager class, which needs to be configured with a list of one
or more AuthenticationProvider instances. These can either be created using syntax elements
provided by the namespace, or they can be standard bean definitions, marked for addition to the list
using the authentication-provider element.

<authentication-manager>
Every Spring Security application which uses the namespace must have include this element
somewhere. It is responsible for registering the AuthenticationManager which provides
authentication services to the application. All elements which create AuthenticationProvider
instances should be children of this element.
<authentication-manager> Attributes
alias This attribute allows you to define an alias name for the internal instance for use in your own
configuration. Its use is described in thenamespace introduction.
erase-credentials If set to true, the AuthenticationManger will attempt to clear any credentials
data in the returned Authentication object, once the user has been authenticated. Literally it maps
to the eraseCredentialsAfterAuthentication property of the ProviderManager. This is
discussed in the Core Services chapter.
id This attribute allows you to define an id for the internal instance for use in your own configuration.
It is the same a the alias element, but provides a more consistent experience with elements that use
the id attribute.
Child Elements of <authentication-manager>
authentication-provider
ldap-authentication-provider

<authentication-provider>
Unless used with a ref attribute, this element is shorthand for configuring a DaoAuthenticationProvider.
DaoAuthenticationProvider loads user information from a UserDetailsService and
compares the username/password combination with the values supplied at login. The
UserDetailsService instance can be defined either by using an available namespace element
( jdbc-user-service or by using the user-service-ref attribute to point to a bean defined
elsewhere in the application context). You can find examples of these variations in the namespace
introduction.
Parent Elements of <authentication-provider>
authentication-manager

4.0.2.RELEASE

Spring Security

212

Spring Security Reference

<authentication-provider> Attributes
ref Defines a reference to a Spring bean that implements `AuthenticationProvider `.
If you have written your own AuthenticationProvider implementation (or want to configure one
of Spring Securitys own implementations as a traditional bean for some reason, then you can use the
following syntax to add it to the internal `ProviderManagers list:
<security:authentication-manager>
<security:authentication-provider ref="myAuthenticationProvider" />
</security:authentication-manager>
<bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider"/>

user-service-ref A reference to a bean that implements UserDetailsService that may be created

using the standard bean element or the custom user-service element.
Child Elements of <authentication-provider>
jdbc-user-service
ldap-user-service
password-encoder
user-service

<jdbc-user-service>
Causes creation of a JDBC-based UserDetailsService.
<jdbc-user-service> Attributes
authorities-by-username-query An SQL statement to query for a users granted authorities given
a username.
The default is
select username, authority from authorities where username = ?

cache-ref Defines a reference to a cache for use with a UserDetailsService.

data-source-ref The bean ID of the DataSource which provides the required tables.
group-authorities-by-username-query An SQL statement to query users group authorities given
a username. The default is
select
g.id, g.group_name, ga.authority
from
groups g, group_members gm, group_authorities ga
where
gm.username = ? and g.id = ga.group_id and g.id = gm.group_id

id A bean identifier, used for referring to the bean elsewhere in the context.
role-prefix A non-empty string prefix that will be added to role strings loaded from persistent storage
(default is "ROLE_"). Use the value "none" for no prefix in cases where the default is non-empty.
users-by-username-query An SQL statement to query a username, password, and enabled status
given a username. The default is

4.0.2.RELEASE

Spring Security

213

Spring Security Reference

select username, password, enabled from users where username = ?

<password-encoder>
Authentication providers can optionally be configured to use a password encoder as described
in the namespace introduction. This will result in the bean being injected with the appropriate
PasswordEncoder instance, potentially with an accompanying SaltSource bean to provide salt
values for hashing.
Parent Elements of <password-encoder>
authentication-provider
password-compare
<password-encoder> Attributes
base64 Whether a string should be base64 encoded
hash Defines the hashing algorithm used on user passwords. We recommend strongly against using
MD4, as it is a very weak hashing algorithm.
ref Defines a reference to a Spring bean that implements `PasswordEncoder `.
Child Elements of <password-encoder>
salt-source

<salt-source>
Password salting strategy. A system-wide constant or a property from the UserDetails object can be
used.
Parent Elements of <salt-source>
password-encoder
<salt-source> Attributes
ref Defines a reference to a Spring bean Id.
system-wide A single value that will be used as the salt for a password encoder.
user-property A property of the UserDetails object which will be used as salt by a password encoder.
Typically something like "username" might be used.

<user-service>
Creates an in-memory UserDetailsService from a properties file or a list of "user" child elements.
Usernames are converted to lower-case internally to allow for case-insensitive lookups, so this should
not be used if case-sensitivity is required.
<user-service> Attributes
id A bean identifier, used for referring to the bean elsewhere in the context.

4.0.2.RELEASE

Spring Security

214

Spring Security Reference

properties The location of a Properties file where each line is in the format of
username=password,grantedAuthority[,grantedAuthority][,enabled|disabled]

Child Elements of <user-service>

user

<user>
Represents a user in the application.
Parent Elements of <user>
user-service
<user> Attributes
authorities One of more authorities granted to the user. Separate authorities with a comma (but no
space). For example, "ROLE_USER,ROLE_ADMINISTRATOR"
disabled Can be set to "true" to mark an account as disabled and unusable.
locked Can be set to "true" to mark an account as locked and unusable.
name The username assigned to the user.
password The password assigned to the user. This may be hashed if the corresponding
authentication provider supports hashing (remember to set the "hash" attribute of the "user-service"
element). This attribute be omitted in the case where the data will not be used for authentication, but
only for accessing authorities. If omitted, the namespace will generate a random value, preventing its
accidental use for authentication. Cannot be empty.

38.4 Method Security

<global-method-security>
This element is the primary means of adding support for securing methods on Spring Security beans.
Methods can be secured by the use of annotations (defined at the interface or class level) or by defining
a set of pointcuts as child elements, using AspectJ syntax.
<global-method-security> Attributes
access-decision-manager-ref Method security uses the same AccessDecisionManager
configuration as web security, but this can be overridden using this attribute. By default an
AffirmativeBased implementation is used for with a RoleVoter and an AuthenticatedVoter.
authentication-manager-ref A reference to an AuthenticationManager that should be used for
method security.
jsr250-annotations Specifies whether JSR-250 style attributes are to be used (for example
"RolesAllowed"). This will require the javax.annotation.security classes on the classpath. Setting this
to true also adds a Jsr250Voter to the AccessDecisionManager, so you need to make sure you
do this if you are using a custom implementation and want to use these annotations.

4.0.2.RELEASE

Spring Security

215

Spring Security Reference

metadata-source-ref An external MethodSecurityMetadataSource instance can be supplied

which will take priority over other sources (such as the default annotations).
mode This attribute can be set to "aspectj" to specify that AspectJ should be used instead of the
default Spring AOP. Secured methods must be woven with the AnnotationSecurityAspect from
the spring-security-aspects module.
It is important to note that AspectJ follows Javas rule that annotations on interfaces are not inherited.
This means that methods that define the Security annotaitons on the interface will not be secured.
Instead, you must place the Security annotation on the class when using AspectJ.
order Allows the advice "order" to be set for the method security interceptor.
pre-post-annotations Specifies whether the use of Spring Securitys pre and post invocation
annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) should be enabled for this
application context. Defaults to "disabled".
proxy-target-class If true, class based proxying will be used instead of interface based proxying.
run-as-manager-ref A reference to an optional RunAsManager implementation which will be used
by the configured MethodSecurityInterceptor
secured-annotations Specifies whether the use of Spring Securitys @Secured annotations should
be enabled for this application context. Defaults to "disabled".
Child Elements of <global-method-security>
after-invocation-provider
expression-handler
pre-post-annotation-handling
protect-pointcut

<after-invocation-provider>
This element can be used to decorate an AfterInvocationProvider for use by the security
interceptor maintained by the <global-method-security> namespace. You can define zero or
more of these within the global-method-security element, each with a ref attribute pointing to
an AfterInvocationProvider bean instance within your application context.
Parent Elements of <after-invocation-provider>
global-method-security
<after-invocation-provider> Attributes
ref Defines a reference to a Spring bean that implements ` AfterInvocationProvider`.

<pre-post-annotation-handling>
Allows the default expression-based mechanism for handling Spring Securitys pre and post invocation
annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) to be replace entirely. Only
applies if these annotations are enabled.

4.0.2.RELEASE

Spring Security

216

Spring Security Reference

Parent Elements of <pre-post-annotation-handling>

global-method-security
Child Elements of <pre-post-annotation-handling>
invocation-attribute-factory
post-invocation-advice
pre-invocation-advice

<invocation-attribute-factory>
Defines the PrePostInvocationAttributeFactory instance which is used to generate pre and post
invocation metadata from the annotated methods.
Parent Elements of <invocation-attribute-factory>
pre-post-annotation-handling
<invocation-attribute-factory> Attributes
ref Defines a reference to a Spring bean Id.

<post-invocation-advice>
Customizes
the
PostInvocationAdviceProvider
with
the
ref
as
PostInvocationAuthorizationAdvice for the <pre-post-annotation-handling> element.

the

Parent Elements of <post-invocation-advice>

pre-post-annotation-handling
<post-invocation-advice> Attributes
ref Defines a reference to a Spring bean Id.

<pre-invocation-advice>
Customizes the PreInvocationAuthorizationAdviceVoter with the ref as the
PreInvocationAuthorizationAdviceVoter for the <pre-post-annotation-handling> element.
Parent Elements of <pre-invocation-advice>
pre-post-annotation-handling
<pre-invocation-advice> Attributes
ref Defines a reference to a Spring bean Id.

Securing Methods using

<protect-pointcut> Rather than defining security attributes on an individual method or class basis
using the @Secured annotation, you can define cross-cutting security constraints across whole sets of

4.0.2.RELEASE

Spring Security

217

Spring Security Reference

methods and interfaces in your service layer using the <protect-pointcut> element. You can find
an example in the namespace introduction.
Parent Elements of <protect-pointcut>
global-method-security
<protect-pointcut> Attributes
access Access configuration attributes list that applies to all methods matching the pointcut, e.g.
"ROLE_A,ROLE_B"
expression An AspectJ expression, including the 'execution' keyword. For example, 'execution(int
com.foo.TargetObject.countLength(String))' (without the quotes).

<intercept-methods>
Can be used inside a bean definition to add a security interceptor to the bean and set up access
configuration attributes for the beans methods
<intercept-methods> Attributes
access-decision-manager-ref Optional AccessDecisionManager bean ID to be used by the created
method security interceptor.
Child Elements of <intercept-methods>
protect

<method-security-metadata-source>
Creates a MethodSecurityMetadataSource instance
<method-security-metadata-source> Attributes
id A bean identifier, used for referring to the bean elsewhere in the context.
use-expressions Enables the use of expressions in the 'access' attributes in <intercept-url> elements
rather than the traditional list of configuration attributes. Defaults to 'false'. If enabled, each attribute
should contain a single boolean expression. If the expression evaluates to 'true', access will be
granted.
Child Elements of <method-security-metadata-source>
protect

<protect>
Defines a protected method and the access control configuration attributes that apply to it. We strongly
advise you NOT to mix "protect" declarations with any services provided "global-method-security".
Parent Elements of <protect>
intercept-methods
method-security-metadata-source

4.0.2.RELEASE

Spring Security

218

Spring Security Reference

<protect> Attributes
access Access configuration attributes list that applies to the method, e.g. "ROLE_A,ROLE_B".
method A method name

38.5 LDAP Namespace Options

LDAP is covered in some details in its own chapter. We will expand on that here with some explanation
of how the namespace options map to Spring beans. The LDAP implementation uses Spring LDAP
extensively, so some familiarity with that projects API may be useful.

Defining the LDAP Server using the

<ldap-server> Element This element sets up a Spring LDAP ContextSource for use by the other
LDAP beans, defining the location of the LDAP server and other information (such as a username and
password, if it doesnt allow anonymous access) for connecting to it. It can also be used to create an
embedded server for testing. Details of the syntax for both options are covered in the LDAP chapter.
The actual ContextSource implementation is DefaultSpringSecurityContextSource which
extends Spring LDAPs LdapContextSource class. The manager-dn and manager-password
attributes map to the latters userDn and password properties respectively.
If you only have one server defined in your application context, the other LDAP namespace-defined
beans will use it automatically. Otherwise, you can give the element an "id" attribute and refer to it
from other namespace beans using the server-ref attribute. This is actually the bean id of the
ContextSource instance, if you want to use it in other traditional Spring beans.
<ldap-server> Attributes
id A bean identifier, used for referring to the bean elsewhere in the context.
ldif Explicitly specifies an ldif file resource to load into an embedded LDAP server. The ldiff is should
be a Spring resource pattern (i.e. classpath:init.ldiff). The default is classpath*:*.ldiff
manager-dn Username (DN) of the "manager" user identity which will be used to authenticate to a
(non-embedded) LDAP server. If omitted, anonymous access will be used.
manager-password The password for the manager DN. This is required if the manager-dn is
specified.
port Specifies an IP port number. Used to configure an embedded LDAP server, for example. The
default value is 33389.
root Optional root suffix for the embedded LDAP server. Default is "dc=springframework,dc=org"
url Specifies the ldap server URL when not using the embedded LDAP server.

user-context-mapper-ref Allows explicit customization of the loaded user object by specifying a

UserDetailsContextMapper bean which will be called with the context information from the users
directory entry
user-details-class Allows the objectClass of the user entry to be specified. If set, the framework will
attempt to load standard attributes for the defined class into the returned UserDetails object
user-search-base Search base for user searches. Defaults to "". Only used with a 'user-search-filter'.
user-search-filter The LDAP filter used to search for users (optional). For example "(uid={0})". The
substituted parameter is the users login name.

4.0.2.RELEASE

Spring Security

222

Spring Security Reference

39. Spring Security Dependencies

This appendix provides a reference of the modules in Spring Security and the additional dependencies
that they require in order to function in a running application. We dont include dependenices that are
only used when building or testing Spring Security itself. Nor do we include transitive dependencies
which are required by external dependencies.
The version of Spring required is listed on the project website, so the specific versions are omitted
for Spring dependencies below. Note that some of the dependencies listed as"optional" below may
still be required for other non-security functionality in a Spring application. Also dependencies listed as
"optional" may not actually be marked as such in the projects Maven pom files if they are used in most
applications. They are"optional" only in the sense that you dont need them unless you are using the
specified functionality.
Where a module depends on another Spring Security module, the non-optional dependencies of the
module it depends on are also assumed to be required and are not listed separately.

39.1 spring-security-core
The core module must be included in any project using Spring Security.
Table 39.1. Core Depenendencies
Dependency

Version

Description

aopalliance

1.0

Required for method security

implementation.

ehcache

1.6.2

Required if the ehcache-based

user cache implementation is
used (optional).

spring-aop

Method security is based on

Spring AOP

spring-beans

Required for Spring

configuration

spring-expression

Required for expression-based

method security (optional)

spring-jdbc

Required if using a database to

store user data (optional).

spring-tx

Required if using a database to

store user data (optional).

aspectjrt

1.6.10

Required if using AspectJ

support (optional).

jsr250-api

1.0

Required if you are using

JSR-250 method-security
annotations (optional).

4.0.2.RELEASE

Spring Security

223

Spring Security Reference

39.2 spring-security-remoting
This module is typically required in web applications which use the Servlet API.
Table 39.2. Remoting Dependencies
Dependency

Version

Description

spring-security-core
spring-web

Required for clients which use

HTTP remoting support.

39.3 spring-security-web
This module is typically required in web applications which use the Servlet API.
Table 39.3. Web Dependencies
Dependency

Version

Description

spring-security-core
spring-web

Spring web support classes are

used extensively.

spring-jdbc

Required for JDBC-based

persistent remember-me token
repository (optional).

spring-tx

Required by remember-me
persistent token repository
implementations (optional).

39.4 spring-security-ldap
This module is only required if you are using LDAP authentication.
Table 39.4. LDAP Dependencies
Dependency

Version

Description

1.3.0

LDAP support is based on

Spring LDAP.

spring-security-core
spring-ldap-core

spring-tx

apache-ds

Data exception classes are

required.
1

4.0.2.RELEASE

1.5.5

Required if you are using

an embedded LDAP server
(optional).

Spring Security

224

Spring Security Reference

Dependency

Version

Description

shared-ldap

0.9.15

Required if you are using

an embedded LDAP server
(optional).

ldapsdk

4.1

Mozilla LdapSDK. Used for

decoding LDAP password
policy controls if you are using
password-policy functionality
with OpenLDAP, for example.

The modules apacheds-core, apacheds-core-entry, apacheds-protocol-shared, apacheds-protocol-ldap and

apacheds-server-jndi are required.

39.5 spring-security-config
This module is required if you are using Spring Security namespace configuration.
Table 39.5. Config Dependencies
Dependency

Version

Description

spring-security-core
spring-security-web

Required if you are using

any web-related namespace
configuration (optional).

spring-security-ldap

Required if you are using the

LDAP namespace options
(optional).

spring-security-openid

Required if you are using

OpenID authentication
(optional).

aspectjweaver

1.6.10

Required if using the protectpointcut namespace syntax

(optional).

39.6 spring-security-acl
The ACL module.
Table 39.6. ACL Dependencies
Dependency

Version

Description

1.6.2

Required if the ehcache-based

ACL cache implementation is
used (optional if you are using
your own implementation).

spring-security-core
ehcache

4.0.2.RELEASE

Spring Security

225

Spring Security Reference

Dependency

Version

Description

openid4java-nodeps

0.9.6

Spring Securitys OpenID

integration uses OpenID4Java.

httpclient

4.1.1

openid4java-nodeps depends
on HttpClient 4.

guice

2.0

openid4java-nodeps depends
on Guice 2.

spring-security-core
spring-security-web

39.9 spring-security-taglibs
Provides Spring Securitys JSP tag implementations.

4.0.2.RELEASE

Spring Security

226

Spring Security Reference

Table 39.9. Taglib Dependencies

Dependency

Version

Description

spring-security-core
spring-security-web
spring-security-acl

Required if you are using

the accesscontrollist
tag or hasPermission()
expressions with ACLs
(optional).

spring-expression

Required if you are using SPEL

expressions in your tag access
constraints.

4.0.2.RELEASE

Spring Security

227

Textnow PDF
100% (1)
Textnow PDF
6 pages
CAN and FPGA Communication Engineering: Implementation of a CAN Bus based Measurement System on an FPGA Development Kit
From Everand
CAN and FPGA Communication Engineering: Implementation of a CAN Bus based Measurement System on an FPGA Development Kit
Yu Zhu
No ratings yet
Apna Tunnel (Data)
No ratings yet
Apna Tunnel (Data)
48 pages
Python Binance Readthedocs Io en Latest
No ratings yet
Python Binance Readthedocs Io en Latest
228 pages
Programming FPGAs: Getting Started with Verilog
From Everand
Programming FPGAs: Getting Started with Verilog
Simon Monk
3.5/5 (2)
Fritzing for Inventors: Take Your Electronics Project from Prototype to Product
From Everand
Fritzing for Inventors: Take Your Electronics Project from Prototype to Product
Simon Monk
No ratings yet
Node - JS, Socket - Io, and Real-Time Web HMI Example - Chris Larson
No ratings yet
Node - JS, Socket - Io, and Real-Time Web HMI Example - Chris Larson
17 pages
Spring Security Reference
No ratings yet
Spring Security Reference
281 pages
Spring Security Reference
No ratings yet
Spring Security Reference
239 pages
Spring Security
No ratings yet
Spring Security
134 pages
Springsecurity
No ratings yet
Springsecurity
134 pages
Spring Security
No ratings yet
Spring Security
134 pages
Spring Security
100% (1)
Spring Security
134 pages
Spring Security
No ratings yet
Spring Security
133 pages
Spring Security Reference
No ratings yet
Spring Security Reference
323 pages
Spring Security
No ratings yet
Spring Security
132 pages
Normal 5f89d02c9d162
No ratings yet
Normal 5f89d02c9d162
2 pages
Spring Security Reference
No ratings yet
Spring Security Reference
138 pages
Guide to Spring Security
No ratings yet
Guide to Spring Security
15 pages
Cloud Computing : Beginners And Intermediate User Guide
From Everand
Cloud Computing : Beginners And Intermediate User Guide
David comer
No ratings yet
Guide to Spring Security
No ratings yet
Guide to Spring Security
16 pages
Benefits of semantic data models. A study in the European goods transport industry
From Everand
Benefits of semantic data models. A study in the European goods transport industry
Andreas A. Pelekies
No ratings yet
Spring Security
No ratings yet
Spring Security
16 pages
Spring Security
No ratings yet
Spring Security
182 pages
Programming the Photon: Getting Started with the Internet of Things
From Everand
Programming the Photon: Getting Started with the Internet of Things
Christopher Rush
5/5 (1)
Spring Security Essentials - Sample Chapter
No ratings yet
Spring Security Essentials - Sample Chapter
14 pages
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet
Spring Security
No ratings yet
Spring Security
107 pages
Spring Security
No ratings yet
Spring Security
33 pages
spring_security
No ratings yet
spring_security
5 pages
Trust in Co-operative Contracting in Construction
From Everand
Trust in Co-operative Contracting in Construction
Sai On Cheung
No ratings yet
Analyzing Food Security using Household Surveys
From Everand
Analyzing Food Security using Household Surveys
World Bank Staff
No ratings yet
Analyzing Food Security Using Household Survey Data: Streamlined Analysis with ADePT Software
From Everand
Analyzing Food Security Using Household Survey Data: Streamlined Analysis with ADePT Software
Ana Moltedo
No ratings yet
Preventing Money Laundering and Terrorist Financing: A Practical Guide for Bank Supervisors
From Everand
Preventing Money Laundering and Terrorist Financing: A Practical Guide for Bank Supervisors
Pierre-Laurent Chatain
No ratings yet
Spring Security
No ratings yet
Spring Security
21 pages
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
From Everand
Programming the Intel Galileo: Getting Started with the Arduino -Compatible Development Board
Christopher Rush
5/5 (1)
Mastering Python Advanced Concepts and Practical Applications
From Everand
Mastering Python Advanced Concepts and Practical Applications
Aissa Younes
No ratings yet
Facility Management: Business Process Integration
From Everand
Facility Management: Business Process Integration
Alexander Redlein
No ratings yet
Programming Arduino Next Steps: Going Further with Sketches
From Everand
Programming Arduino Next Steps: Going Further with Sketches
Simon Monk
3/5 (3)
Sourcebook on the Foundations of Social Protection Delivery Systems
From Everand
Sourcebook on the Foundations of Social Protection Delivery Systems
Kathy Lindert
No ratings yet
Crypto Currencies and Traditional Investment Portfolios. An Empirical Study on the Effects of Adding Crypto Currencies to Traditional Investment Portfolios
From Everand
Crypto Currencies and Traditional Investment Portfolios. An Empirical Study on the Effects of Adding Crypto Currencies to Traditional Investment Portfolios
Philipp Rosenbach
No ratings yet
Gray Hat Hacking the Ethical Hacker's
From Everand
Gray Hat Hacking the Ethical Hacker's
Çağatay Şanlı
5/5 (1)
08 Spring Boot 3 Spring MVC Security
No ratings yet
08 Spring Boot 3 Spring MVC Security
158 pages
Spring Security Reference
No ratings yet
Spring Security Reference
555 pages
springsecurity-181008152249
No ratings yet
springsecurity-181008152249
36 pages
Plain JavaScript: Learning the Front-End
From Everand
Plain JavaScript: Learning the Front-End
Roger Beans-Rivet
No ratings yet
Web 2.0 and the Health Care Market: Health Care in the era of Social Media and the modern Internet
From Everand
Web 2.0 and the Health Care Market: Health Care in the era of Social Media and the modern Internet
Sabrina Sturm
No ratings yet
Austin and Boxerman's Information Systems for Healthcare Management, Seventh Edition
From Everand
Austin and Boxerman's Information Systems for Healthcare Management, Seventh Edition
Gerald L. Glandon
No ratings yet
Spring Security 5
No ratings yet
Spring Security 5
28 pages
Programming Arduino: Getting Started with Sketches
From Everand
Programming Arduino: Getting Started with Sketches
Simon Monk
3.5/5 (5)
Open Innovation and Business Success
From Everand
Open Innovation and Business Success
Monika Gawarzynska
No ratings yet
Copyright for Dummies. Your guide to copyright in Russia.
From Everand
Copyright for Dummies. Your guide to copyright in Russia.
Leontyev, Кonstantin B.
No ratings yet
Next Generation Environmental Compliance and Enforcement
From Everand
Next Generation Environmental Compliance and Enforcement
LeRoy C. Paddock
No ratings yet
Electronics from the Ground Up: Learn by Hacking, Designing, and Inventing
From Everand
Electronics from the Ground Up: Learn by Hacking, Designing, and Inventing
Ronald Quan
3.5/5 (2)
Spring Security: Authentication Authorization
100% (1)
Spring Security: Authentication Authorization
4 pages
Spring Security 3.0: by Tanuj Kathuria
No ratings yet
Spring Security 3.0: by Tanuj Kathuria
12 pages
Spring Security Zero To Master Along With JWT, OAUTH2
No ratings yet
Spring Security Zero To Master Along With JWT, OAUTH2
106 pages
Spring Security: Basic Steps & Configuration
No ratings yet
Spring Security: Basic Steps & Configuration
14 pages
Programming Arduino Next Steps: Going Further with Sketches, Second Edition
From Everand
Programming Arduino Next Steps: Going Further with Sketches, Second Edition
Simon Monk
3/5 (3)
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
From Everand
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
Michael Basler
No ratings yet
462 Solution Code Spring Security Demo 08 JDBC Plaintext
No ratings yet
462 Solution Code Spring Security Demo 08 JDBC Plaintext
14 pages
Teardowns: Learn How Electronics Work by Taking Them Apart
From Everand
Teardowns: Learn How Electronics Work by Taking Them Apart
Bryan Bergeron
No ratings yet
A To Z of Internet: Everything You Wanted to Know
From Everand
A To Z of Internet: Everything You Wanted to Know
Bittu Kumar
No ratings yet
Beyond the Gap: How Countries Can Afford the Infrastructure They Need while Protecting the Planet
From Everand
Beyond the Gap: How Countries Can Afford the Infrastructure They Need while Protecting the Planet
Rozenberg
No ratings yet
Webrtc
No ratings yet
Webrtc
44 pages
All Included Webrtc Training For Developers: A Separate Course For Support Teams Is Available
No ratings yet
All Included Webrtc Training For Developers: A Separate Course For Support Teams Is Available
12 pages
Application Protocol - Web Socket
No ratings yet
Application Protocol - Web Socket
19 pages
Connection Log
No ratings yet
Connection Log
10 pages
Practical Rust Web Projects: Building Cloud and Web-Based Applications Shing Lyu all chapter instant download
100% (12)
Practical Rust Web Projects: Building Cloud and Web-Based Applications Shing Lyu all chapter instant download
55 pages
user-manual
No ratings yet
user-manual
36 pages
Live Transcribing Phone Calls Using Twilio Media Streams and Google Speech-to-Text
No ratings yet
Live Transcribing Phone Calls Using Twilio Media Streams and Google Speech-to-Text
21 pages
socket.io
No ratings yet
socket.io
8 pages
Slide - WCF 4.5
No ratings yet
Slide - WCF 4.5
41 pages
Web RTC Certified Developer Course Outline
No ratings yet
Web RTC Certified Developer Course Outline
9 pages
Configure Remote Console Access: Nova 18.3.1.dev35
No ratings yet
Configure Remote Console Access: Nova 18.3.1.dev35
7 pages
Session II
No ratings yet
Session II
67 pages
Bug Inject
No ratings yet
Bug Inject
20 pages
Az 220 Dump1
No ratings yet
Az 220 Dump1
73 pages
Cisco Finesse Web Services Developer JavaScript Guide Release 12.5
No ratings yet
Cisco Finesse Web Services Developer JavaScript Guide Release 12.5
562 pages
Here Come The XOR Ninjas
No ratings yet
Here Come The XOR Ninjas
10 pages
OOPS With Java Unit 5
No ratings yet
OOPS With Java Unit 5
21 pages
VPN V98
No ratings yet
VPN V98
26 pages
Course Syllabus
No ratings yet
Course Syllabus
6 pages
Blockchain-Prep Document For Interview
No ratings yet
Blockchain-Prep Document For Interview
3 pages
Programming The Internet of Things
100% (1)
Programming The Internet of Things
86 pages
Iot Unit1
No ratings yet
Iot Unit1
41 pages
ProctorEdu OpenDoors en Manual
No ratings yet
ProctorEdu OpenDoors en Manual
7 pages
Aveva Intouch Access Anywhere Server Administrator Manual
No ratings yet
Aveva Intouch Access Anywhere Server Administrator Manual
47 pages
Ac Services Log
No ratings yet
Ac Services Log
39 pages
Elektor Special Guest-Edited by Arduino 1
100% (3)
Elektor Special Guest-Edited by Arduino 1
140 pages