How Authentication Works in Roller

How Roller authentication works

For a variety of reasons that I'll touch on later, Roller uses Spring Security, also known as Acegi, instead of standard Java EE Servlet Authentication to implement user authentication. To explain how Roller authentication works, I'll explain how we integrated Acegi into Roller and what each part of Acegi does for us. Here's what we added when we started using Acegi in Roller:

• The Acegi jars to Roller's WEB-INF/lib directory
• An Acegi configuration at WEB-INF/security.xml
• The Acegi Servlet Filter and Spring Context listener to Roller's web.xml file
• Some code to RollerContext to do some programatic configuration of Acegi

You can check the Acegi documentation for detail about what jars to add. Let's talk about the configuration files, but first, a word about users and roles in Roller. In Roller, we have two global roles for users: 'admin' for the System Administrators who maintain the site and 'editor' for bloggers who login to blog. We use our URL structure to organize the Roller UI into sections for admin users and sections for editors. We store usernames and passwords in one database table and user roles in another. We rely on Acegi to protect the URLs we want to be protected and to authenticate users against our user tables.

What's going on in security.xml

To configure Acegi to protect our URLs and to authenticate against the Roller user and role tables, we create a twisty maze of nested Java beans strung together by XML in the Acegi configuration file security.xml. You'll have to understand a bit about Spring and spend some time reading the Acegi Javadocs before you can write one yourself. I'll explain what Roller's does at a high-level.

To define the URLs to be protected and the roles required for each, we configure a FilterSecurityInterceptor with the rules listed below in security.xml. The rules say that most URL patterns require either the admin or editor role, but the /roller-ui/admin and /rewrite-status URLs are only for admin users.

{{{
/roller-ui/login-redirect**=admin,editor
/roller-ui/profile**=admin,editor
/roller-ui/createWeblog**=admin,editor
/roller-ui/menu**=admin,editor
/roller-ui/authoring/**=admin,editor
/roller-ui/admin/**=admin
/rewrite-status*=admin
}}}

To setup Acegi to authenticate against the Roller database, we configure a Acegi ProviderManager, which has a Acegi DaoAuthenticationProvider, which has a RollerUserDetailsService, a Roller provided class that creates an Acegi UserDetails object by reading from the Roller database. That's how Acegi gets user and role information from Roller. And we configure various other beans to tell Acegi that the Roller login page is at URL /roller-ui/login.rol, the login error page is /roller-ui/login.rol?error=true and to configure Acegi's Remember Me feature.

The RollerUserDetailsService uses Roller's database layer to fetch user details. So, we don't have to ask our users to go through the tedious and error prone process of seting up a JDBC Realm as we would have had to do if we were using plain old Servlet Authentication.

What's going on in web.xml

We add the Acegi Servlet Filter to Roller's web.xml because that's how Acegi works its magic. Acegi's filter, which gets called first for each incoming request, checks to see if the request is authenticated. If it is, then Acegi wraps the incoming HttpServletRequest object to ensure that request.isUserInRole() and request.getUserPrincipal() return the right values. If not, then Acegi redirects the user to the login page and then back to the originally requested page on successful login or to the login error page on failure.

We also need a Context Listener so we can programmatically initialize parts of Acegi. Here's why. It's great that Acegi is so flexible and you can do so much with security.xml, but in Roller we want our users to have to edit at most one and only one configuration file to get up and running. We want that file to be a simple name and value properties file and certainly not a complicated XML file that references beans defined in some Java API. So, for example, if you want to enable or disable any of the features below, you edit properties in your roller-custom.properties file and Roller uses those property values to initialize Acegi programmatically, i.e. by calling the Acegi Java API directly.

• Remember Me: allows users to say logged-in for two weeks or until they explicitly logout
• Force Secure Login: force HTTPS for login and password editing pages, HTTP for everything else [1]
• Encrypted Passwords: turn off password encryption

Those features are a benefit of using Acegi instead of plain-old Servlet Authentication. With Servlet Authentication, we'd have to implement those features in Roller and some would be impossible because there is no way to dynamically configure authenticaition through the Servlet API.

For most Roller setups you'll never have to touch security.xml and you can do everything through your roller-custom.properties file, but for more advanced configurations like LDAP or SSO you will probably need to understand how to deal with Acegi and security.xml.

The end

[1] security experts frown at Force Secure Login, but Roller site administrators want that option.