Migration to Spring Security 3

Spring Security 3

May 2010


Secure your web applications against malicious intruders with this easy to follow practical guide

(For more resources on Spring, see here.)

During the course of this article we will:

  • Review important enhancements in Spring Security 3
  • Understand configuration changes required in your existing Spring Security 2 applications when moving them to Spring Security 3
  • Illustrate the overall movement of important classes and packages in Spring Security 3

Once you have completed the review of this article, you will be in a good position to migrate an existing application from Spring Security 2 to Spring Security 3.

Migrating from Spring Security 2

You may be planning to migrate an existing application to Spring Security 3, or trying to add functionality to a Spring Security 2 application and looking for guidance. We'll try to address both of your concerns in this article.

First, we'll run through the important differences between Spring Security 2 and 3—both in terms of features and configuration. Second, we'll provide some guidance in mapping configuration or class name changes. These will better enable you to translate the examples from Spring Security 3 back to Spring Security 2 (where applicable).

A very important migration note is that Spring Security 3 mandates a migration to Spring Framework 3 and Java 5 (1.5) or greater. Be aware that in many cases, migrating these other components may have a greater impact on your application than the upgrade of Spring Security!

Enhancements in Spring Security 3

Significant enhancements in Spring Security 3 over Spring Security 2 include the following:

  • The addition of Spring Expression Language (SpEL) support for access declarations, both in URL patterns and method access specifications.
  • Additional fine-grained configuration around authentication and accessing successes and failures.
  • Enhanced capabilities of method access declaration, including annotationbased pre-and post-invocation access checks and filtering, as well as highly configurable security namespace XML declarations for custom backing bean behavior.
  • Fine-grained management of session access and concurrency control using the security namespace.
  • Noteworthy revisions to the ACL module, with the removal of the legacy ACL code in o.s.s.acl and some important issues with the ACL framework are addressed.
  • Support for OpenID Attribute Exchange, and other general improvements to the robustness of OpenID.
  • New Kerberos and SAML single sign-on support through the Spring Security Extensions project.

Other more innocuous changes encompassed a general restructuring and cleaning up of the codebase and the configuration of the framework, such that the overall structure and usage makes much more sense. The authors of Spring Security have made efforts to add extensibility where none previously existed, especially in the areas of login and URL redirection.

If you are already working in a Spring Security 2 environment, you may not find compelling reasons to upgrade if you aren't pushing the boundaries of the framework. However, if you have found limitations in the available extension points, code structure, or configurability of Spring Security 2, you'll welcome many of the minor changes that we discuss in detail in the remainder of this article.

Changes to configuration in Spring Security 3

Many of the changes in Spring Security 3 will be visible in the security namespace style of configuration. Although this article cannot cover all of the minor changes in detail, we'll try to cover those changes that will be most likely to affect you as you move to Spring Security 3.

Rearranged AuthenticationManager configuration

The most obvious changes in Spring Security 3 deal with the configuration of the AuthenticationManager and any related AuthenticationProvider elements. In Spring Security 2, the AuthenticationManager and AuthenticationProvider configuration elements were completely disconnected—declaring an AuthenticationProvider didn't require any notion of an AuthenticationManager at all.

<jdbc-user-service data-source-ref="dataSource"

In Spring Security 2 to declare the <authentication-manager> element as a sibling of any AuthenticationProvider.

<authentication-manager alias="authManager"/>
<jdbc-user-service data-source-ref="dataSource"/>
<ldap-authentication-provider server-ref="ldap://localhost:10389/"/>

In Spring Security 3, all AuthenticationProvider elements must be the children of <authentication-manager> element, so this would be rewritten as follows:

<authentication-manager alias="authManager">
<jdbc-user-service data-source-ref="dataSource"
<ldap-authentication-provider server-ref=

Of course, this means that the <authentication-manager> element is now required in any security namespace configurations.

If you had defined a custom AuthenticationProvider in Spring Security 2, you would have decorated it with the <custom-authentication-provider> element as part of its bean definition.

<bean id="signedRequestAuthenticationProvider"
<property name="userDetailsService" ref="userDetailsService"/>
<!-- ... -->

While moving this custom AuthenticationProvider to Spring Security 3, we would remove the decorator element and instead configure the AuthenticationProvider using the ref attribute of the <authentication-provider> element as follows:

<authentication-manager alias="authenticationManager">
<authentication-provider ref=

Of course, the source code of our custom provider would change due to class relocations and renaming in Spring Security 3—look later in the article for basic guidelines, and in the code download for this article to see a detailed mapping.

New configuration syntax for session management options

In addition to continuing support for the session fixation and concurrency control features from prior versions of the framework, Spring Security 3 adds new configuration capabilities for customizing URLs and classes involved in session and concurrency control management. If your older application was configuring session fixation protection or concurrent session control, the configuration settings have a new home in the <session-management> directive of the <http> element.

In Spring Security 2, these options would be configured as follows:

<http ... session-fixation-protection="none">
<!-- ... -->
<concurrent-session-control exception-if-maximum-exceeded
="true" max-sessions="1"/>

The analogous configuration in Spring Security 3 removes the session-fixation-protection attribute from the <http> element, and consolidates as follows:

<http ...>
<session-management session-fixation-protection="none">
<concurrency-control error-if-maximum-exceeded
="true" max-sessions="1"/>

You can see that the new logical organization of these options is much more sensible and leaves room for future expansion.

(For more resources on Spring, see here.)

Changes to custom filter configuration

Many users of Spring Security 2 have developed custom authentication filters (or other filters to alter the flow of a secured request). As with custom authentication providers, such filters were previously indicated through decoration of a bean with the <custom-filter> element. This made it a bit difficult in some cases to tie the configuration of a filter directly to the Spring Security configuration.

Let's see an example of the configuration for the signed request header filter as applied to a Spring Security 2 environment.

<bean id="requestHeaderFilter" class="com.packtpub
<security:custom-filter after="AUTHENTICATION_PROCESSING_FILTER"/>
<property name="authenticationManager"

Contrast this with the same configuration from Spring Security 3, and you can see that the bean definition and security wiring are done independently. The custom filter is declared within the <http> element as follows:

<http ...>
<!-- ... -->
<custom-filter ref="requestHeaderFilter"
<!-- ... -->

The bean declaration remains the same as in Spring Security 2, although, as you'd expect, the code for a custom filter is quite different. We've included the sample code—using Spring Security 2 classes—for this filter along with this article, to provide you with some guidance as to what a custom filter should look like before and after translation to Spring Security 3.

Also, the logical filter names for some of the filters have changed in Spring Security 3. We present the list of changes in the following list:

Spring Security 2

Spring Security 3












Removed in Spring Security 3

You must make these changes in your configuration files in addition to relocating the <custom-filter> element.

Changes to CustomAfterInvocationProvider

One final bean decoration from Spring Security 2 has been replaced by a straight, inline element reference, a CustomAfterInvocationProvider declared by the <custom-after-invocation-provider> element.

<bean id="customAfterInvocationProvider"

Similar to what we saw with the other bean decorators from Spring Security 2, in Spring Security 3, this element has been moved within the <global-methodsecurity> declaration, with a simple bean reference.

<global-method-security ...>
<after-invocation-provider ref="customAfterInvocationProvider"/>

Minor configuration changes

The following points will briefly state the additional changes in configuration attributes between Spring Security 2 and 3:

  • While using the auto-config attribute in Spring Security 3, remember me services are no longer configured by default. You will need to explicitly add the <remember-me> declaration within your <http> element.
  • For LDAP configuration, the default value for group-search-base-attribute (used in LDAP authorities search) changed in Spring Security 3 from ou=Groups to an empty string (the root of the LDAP tree).
  • The <filter-invocation-definition-source> decoration element, used for configuring a filter chain manually, has been renamed in Spring Security 3 to <filter-security-metadata-source>.
  • The attribute exception-if-maximum-exceeded, related to the <concurrent-session-control> element, has been moved and renamed in Spring Security 3 to error-if-maximum-exceeded, on the new <concurrency-control> element.
  • While using the in memory DAO UserDetailsService, the password attribute is no longer required in Spring Security 3 when declaring users in the configuration file.
  • Built-in support for NTLM authentication has been removed in Spring Securitiy 3 and is intended to be replaced with Kerberos authentication. This remains a point of concern among upgrading users and some activity exists in the Spring Security community to retrofit Spring Security 3 with NTLM support.

The remainder of the changes in the XML configuration dialect for Spring Security 3 represent additions to functionality, and will not cause migration issues for existing applications configured with the security namespace.

Changes to packages and classes

Although in very straightforward applications of Spring Security 2, the locations of classes in packages may not matter, most applications of Spring Security don't end up being free from some kind of ties with the underlying code. So, we felt it would be helpful to point you in the direction of many of the overall package migrations and class renames that occurred between Spring Security 2 and 3.

Wherever possible, we have tried to map classes as accurately as we could—an overview of the major package moves are provided here, and (should you need it) a more comprehensive list is provided as a download with the source code. The table indicates the biggest relocations of classes from Spring Security 2 to Spring Security 3—we've truncated the table to include majority of changes you're likely to see.

Number of classes

Location in Spring 2

Location in Spring 3







































































If it appears to you that classes moved substantially, you are correct! Very few classes were untouched in the overall package reorganization as part of Spring Security 3. Hopefully, this overview points you in the right direction for classes that you may be looking for. Again, please consult the downloads for this article to review a detailed class-by-class mapping.

The benefit to this reorganization is that the entire framework is now much more modular, and fits into discrete JAR files containing only particular elements of functionality, as indicated in the following table:

JAR name



ACL support


CAS support


Overall configuration support


Core framework and classes


LDAP support


OpenID support


JSP Tag Library support


Web tier support

This modularization means that, for example, it is possible to deploy Spring Security to a non-web application without any web dependencies (spring-security-config and spring-security-core might even be enough for your needs).


This article reviewed the major and minor changes that you will find when upgrading an existing Spring Security 2 project to Spring Security 3. In this article we have:

  • Reviewed the significant enhancements to the framework that are likely to motivate an upgrade
  • Examined upgrade requirements, dependencies, and common types of code and configuration changes that will prevent applications from working post-upgrade
  • Investigated (at a high level) the overall code-reorganization changes that the Spring Security authors made as part of the codebase restructuring

Further resources on this subject:

Books to Consider

comments powered by Disqus