Spring Acegi Tutorial

A tutorial on using the Spring Acegi Security Framework to secure web applications.

Bart van Riel

Capgemini Netherlands - Sector Public - Practice D75 "MOJO"

Version 1.1 - May 2006

Table of Contents

1 Introduction 3

1.1 Why this tutorial 3

1.2 Tutorial objectives 3

2 Sources, IDE & other bare necessities 4

2.1 Sources 4

2.2 IDE & Application server 4

2.3 Other bare necessities: Spring and Acegi 4

3 A short discussion on security 5

3.1 Authentication 5

3.2 Authorization 5

3.3 The Four Checks 6

4 The example application 7

4.1 Functionality 7

4.1.1 The Normal User area 7

4.1.2 The Administrator area 9

5 Acegi Web Security 11

5.1 The Authentication object 11

5.2 Filters 11

5.3 Configuration 11

5.3.1 The Filter Chain 12

5.3.2 The AuthenticationProcessingFilter 12

5.3.3 The HttpSessionContextIntegrationFilter 14

5.3.4 The ExceptionTranslationFilter 14

5.3.5 FilterSecurityInterceptor 15

5.4 Using an authentication database through JDBC 18

6 To conclude 19

7 Resources 19

1Introduction

This tutorial describes the configuration of webapplication security using the Acegi Security Framework for Spring.

1.1Why this tutorial

Configuration of Acegi is a complex task Acegi has a rich architecture for implementing security and many options to configure it. Although there are numerous tutorials and book chapters devoted to this, I have had to consult several documentation sources and combine the provided information to get the complete picture. All kinds of problems arose (outdated configuration examples, mixing current and deprecated versions of the various frameworks leading to strange configuration exceptions and so on and so on). Apparently, implementing webapplication security using Acegi is powerful but not a very trivial task. I hope to give the interested reader a compact overview of “the way to do it”, simply making things work without going into details of the frameworks and without the sidestepping into additional (but non-essential) configuration options most books delve into.

1.2Tutorial objectives

This tutorial should give the reader:

• An understanding of the basic principles and the mechanics of webapplication security;

• Insight in the mechanics of Acegi to achieve this security;

• An understanding of the configuration options to make Acegi do it's thing;

• Providing a sample application for the developer to build upon for yer' own fun & games.

2Sources, IDE & other bare necessities

2.1Sources

The sources for this tutorial can be found in “SpringAcegiTutorial.zip”. It is an Eclipse WebTools Project web project and should be imported into the Eclipse WTP workspace.

2.2IDE & Application server

I used Eclipse WebTools Project (WTP) 1.0.2. It can be download from http://download.eclipse.org/webtools/downloads/. Look for the “all in one” bundle which gives you the entire IDE you need. Note that you need a fairly recent JDK to run it.

I used Apache Tomcat 5.5 as my application server. Get it through http://tomcat.apache.org. Getting the Windows installer .exe is the easiest option (provided you run Windows, of course). Note that you will need J2SE 5.0 to run this release of tomcat.

2.3Other bare necessities: Spring and Acegi

I used Spring version 1.2-rc1. You may download it from http://www.springframework.org, but the required libraries have already been included in the “SpringAcegiTutorial.zip” file (to be honest, I have included too much because I packaged the complete spring.jar in stead of the selected spring-xxx.jars but hey, I am the stereotypical lazy programmer).

For Acegi I included the Acegi library jar in the zip file, which is version 1.0.0-RC2. You can download the full stuff from http://www.acegisecurity.org if you wish, but it is not necessary for this tutorial.

3A short discussion on security

Before we delve into any code and Ageci's configuration, a few words on security. In particular, a few words on authentication, authorization and the steps you go through when requesting a resource from a secure webapplication.

3.1Authentication

Authentication pertains to the question “Who are you?”. Usually a user authenticates himself by successfully associating his “principal” (often a username) with his “credentials” (often a password).

3.2Authorization

Authorization pertains to the question “What may you do?”. In J2EE applications, this is achieved by making secured resources accessible (“requestable” in web applications) to particular “roles”. Principals (i.e. users) who are associated with one or more of these roles will have access to those resources.

The motions of a secured web application

So what happens when you access a secured web application resource? The diagram below shows the typical rundown of accessing a web resource with security enabled.

And now in verbose mode: the usual path is 1) check if the resource is secured; 2) check if the requesting user has been authenticated; 3) check if the authenticated user is properly authorized to access the requested resource and 4) serve the requested resource. If the user has not been authenticated yet, walk through the Login dialog. If anything is out of order, display the corresponding error page. Or, if the resource is not secure, skip all previously mentioned steps and serve the resource right away.

3.3The Four Checks

To make a long story short, security is implemented by these Four Checks:

1. the Restricted Access Check (is the resource secured?);

2. the Existing Authentication Check (has the user been authenticated?);

3. if there is no valid login for the user: the Authentication Request Check (are the correct username and password provided?);

4. the Authorization Check (does the user have the required roles?);

4The example application

4.1Functionality

Since this tutorial is intended to give an example of Sprint Acegi configuration for web application authentication and authorization, that is exactly what the example application illustrates. The application has two “area's”, one area is only accessible to normal logged-in users and the other area is the administrator's page. Normal users and administrators do not have access to each other's area, only to their own. Of course, to access either of those area's you need to log in.

4.1.1The Normal User area

Here is the index page, accessible through “http://localhost:8080/springweb”:

Click on the “Try out the submit form” link. You should see the login page:

Login with “bouerj / ineedsleep”. You will bee directed to the Submit Form:

The “submit form” is the function for normal users and enables you to perform the incredibly useful task of submitting two text parameters which will be shown concatenated on the resulting page. There is also a validator on those two fields which prevents you from entering only spaces or nothing at all.

If you enter for example:

and click “Send >”, you should see:

Advanced, is it not?

You can log off by clicking the “<< Log out” link, which calls the URL “http://localhost:8080/springweb/logout.htm”, which will take you back to the index page.

4.1.2The Administrator area

Open the browser again and fire up the index page:

Click on the “Go to the Administrator page” link and you should see the login page again:

Enter “jklaassen / 4moreyears” and you get to the “Administrator area”:

That's all!

So, you can start playing around a bit with various logins and see what happens when you use the wrong login for accessing an area. When you are ready (or fed up with it ;-) ), read on to the part

about configuring all this.

5Acegi Web Security

5.1The Authentication object

The Authentication object is pivotal to the Acegi framework. Since “security” basically means “restricted access for specific roles” the framework has to be able to determine, at any time, the roles given to the authenticated user. The framework stores this info in the “Authentication” object, which contains the username, password and the roles granted to the user.

The Authentication object is created and validated by the by the AuthenticationManager. Access to resources is controlled by the AccessDecisionManager.

5.2Filters

Acegi uses a chain of (at least) three filters to enable webapplication security:

1. The AuthenticationProcessingFilter handles the Authentication Request Check (“logging into the application”). It uses the AuthenticationManager to do its work.

2. The HttpSessionContextIntegrationFilter maintains the Authentication object between various requests and passes it around to the AuthenticationManager and the AccessDecisionManager when needed;

3. The ExceptonTranslationFilter performs the Existing Authentication Check, handles security exceptions and takes the appropriate action. This action can be either spawning the authentication dialog (a.k.a. the login form) or returning the appropriate HTTP security error code. ExceptonTranslationFilter depends on the next filter, FilterSecurityInterceptor, to do its work.

4. FilterSecurityInterceptor manages the Restricted Acces Check,and the Authorisation check. It knows which resources are secure and which roles have access to them. FilterSecurityInterceptor uses the AuthenticationManager and  AccessDecisionManager to do its work.

In good Spring and Dependency Injection fashion, the classes described above do not do their work alone and serve mainly as proxies who delegate the hard work to other classes. I will describe those classes in more detail while laying out the configuration file later on.

5.3Configuration

Since Acegi depends on the Spring framework, all configuration is done through “wiring”. Without going into too much detail, “wiring” means associating JavaBeans with each other via a XML configuration file. The three filters mentioned in the previous paragraph need all their dependent objects “wired” into them. We will get to the XML configuration in a moment, but first it might be a good idea to graphically outline the dependencies between the three filters and the various “utility objects” they use.

5.3.1The Filter Chain

As you saw in the graph in paragraph 5.2, the three filters form a chain through which every HTTP request passes. Together, the three filters perform the task of securing the application. The three filters are “chained” together by an object called the “filterChainProxy”, which in turn creates and starts the three filters. See the diagram below:

In good Spring fashion, the three filters are started by yet another object, the “FilterChainProxy”. This proxy is configured in the configuration XML file and any additional filters (we will come to some of them later on) will be added to the “FilterChainProxy” configuration list.

The XML configuration is like this:

<bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy">

<property name="filterInvocationDefinitionSource">

<value>

CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON

PATTERN_TYPE_APACHE_ANT

/**=httpSessionContextIntegrationFilter,formAuthenticationProcessingFilter,

exceptionTranslationFilter,filterSecurityInterceptor

value>