# Frequently Asked Questions

## What is Acegi Security?

Acegi Security is an open source project that provides comprehensive authentication and authorisation services for enterprise applications based on The Spring Framework. Acegi Security can authenticate using a variety of pluggable providers, and can authorise both web requests and method invocations. Acegi Security provides an integrated security approach across these various targets, and also offers access control list (ACL) capabilities to enable individual domain object instances to be secured. At an implementation level, Acegi Security is managed through Spring's inversion of control and lifecycle services, and actually enforces security using interception through servlet Filters and Java AOP frameworks. In terms of AOP framework support, Acegi Security currently supports AOP Alliance (which is what the Spring IoC container uses internally) and AspectJ, although additional frameworks can be easily supported.

## Why not just use web.xml security?

Let's assume you're developing an enterprise application based on Spring. There are four security concerns you typically need to address: authentication, web request security, service layer security (ie your methods that implement business logic), and domain object instance security (ie different domain objects have different permissions). With these typical requirements in mind:

1. Authentication: The servlet specification provides an approach to authentication. However, you will need to configure the container to perform authentication which typically requires editing of container-specific "realm" settings. This makes a non-portable configuration, and if you need to write an actual Java class to implement the container's authentication interface, it becomes even more non-portable. With Acegi Security you achieve complete portability - right down to the WAR level. Also, Acegi Security offers a choice of production-proven authentication providers and mechanisms, meaning you can switch your authentication approaches at deployment time. This is particularly valuable for software vendors writing products that need to work in an unknown target environment.
2. Web request security: The servlet specification provides an approach to secure your request URIs. However, these URIs can only be expressed in the servlet specification's own limited URI path format. Acegi Security provides a far more comprehensive approach. For instance, you can use Ant paths or regular expressions, you can consider parts of the URI other than simply the requested page (eg you can consider HTTP GET parameters), and you can implement your own runtime source of configuration data. This means your web request security can be dynamically changed during the actual execution of your webapp.
3. Service layer and domain object security: The absence of support in the servlet specification for services layer security or domain object instance security represent serious limitations for multi-tiered applications. Typically developers either ignore these requirements, or implement security logic within their MVC controller code (or even worse, inside the views). There are serious disadvantages with this approach:
   1. Separation of concerns: Authorization is a crosscutting concern and should be implemented as such. MVC controllers or views implementing authorization code makes it more difficult to test both the controller and authorization logic, more difficult to debug, and will often lead to code duplication.
   2. Support for rich clients and web services: If an additional client type must ultimately be supported, any authorization code embedded within the web layer is non-reusable. It should be considered that Spring remoting exporters only export service layer beans (not MVC controllers). As such authorization logic needs to be located in the services layer to support a multitude of client types.
   3. Layering issues: An MVC controller or view is simply the incorrect architectural layer to implement authorization decisions concerning services layer methods or domain object instances. Whilst the Principal may be passed to the services layer to enable it to make the authorization decision, doing so would introduce an additional argument on every services layer method. A more elegant approach is to use a ThreadLocal to hold the Principal, although this would likely increase development time to a point where it would become more economical (on a cost-benefit basis) to simply use a dedicated security framework.
   4. Authorisation code quality: It is often said of web frameworks that they "make it easier to do the right things, and harder to do the wrong things". Security frameworks are the same, because they are designed in an abstract manner for a wide range of purposes. Writing your own authorization code from scratch does not provide the "design check" a framework would offer, and in-house authorization code will typically lack the improvements that emerge from widespread deployment, peer review and new versions.

For simple applications, servlet specification security may just be enough. Although when considered within the context of web container portability, configuration requirements, limited web request security flexibility, and non-existent services layer and domain object instance security, it becomes clear why developers often look to alternative solutions.

## How do you pronounce "Acegi"?

Ah-see-gee. Said quickly, without emphasis on any part. Acegi isn't an acronym, name of a Greek God or anything similarly impressive - it's just letters #1, #3, #5, #7 and #9 of the alphabet.

## Is it called "Acegi" or "Acegi Security"?

It's official name is Acegi Security System for Spring, although we're happy for it to be abbreviated to Acegi Security. Please don't just call it Acegi, though, as that gets confused with the name of the company that maintains Acegi Security.

## What catches 80% of users reporting problems?

80% of support questions are because people have not defined the necessary filters in `web.xml`, or the filters are being mapped in the incorrect order. Check the Reference Guide, which has a specific section on filter ordering.

## I'm sure my filters are ordered correctly. What else could be wrong?

The next most common source of problems stem from custom `AuthenticationDao` implementations that simply don't properly implement the interface contract. For example, they return `null` instead of the user not found exception, or fail to add in the `GrantedAuthority[]`s. Whilst `DaoAuthenticationProvider` does its best to check the `AuthenticationDao` returns a valid `UserDetails`, we suggest you write the `UserDetails` object to the log and check it looks correct.

## Common Problem #1: My application goes into an "endless loop" when I try to login, what's going on?

A common user problem with infinite loop and redirecting to the login page is caused by accidently configuring the login page as a "secured" resource. Generally make sure you mark your login page as requiring ROLE_ANONYMOUS.

## Common Problem #2: My application pages don't seem to be protected.

If you are securing web resources and they dont seem to be matched in the URL patterns, check the objectDefinitionSource in the FilterSecurityInterceptor. If you are using the `CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON` setting, then the URL patterns configured MUST be in lowercase.

For example, making a request ending in `/someAction.do` will need to be configured as: `/someaction.do` (Note the case).

    <property name="objectDefinitionSource">
      <value>
        CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
        PATTERN_TYPE_APACHE_ANT
        /index.jsp=ROLE_ANONYMOUS,ROLE_USER
        /someaction.do=ROLE_USER
      <value>
    </property>

## Common Problem #3: How do I disable a user after a number of failed logins?

A common user requirement is to disable / lock an account after a number of failed login attempts. Acegi itself does not provide anything "out of the box", however in your application you can implement and register an `org.springframework.context.ApplicationListener`. Inside your application event listener you can then check for an instanceof the particular `AuthenticationFailureEvent` and then call your application user management interface to update the user details.

For example:

         public void onApplicationEvent(ApplicationEvent event) {

           // check failed event
           if(event instanceof AuthenticationFailurePasswordEvent){
              // call user management interface to increment failed login attempts, etc.
              . . .
           }
         }

## Common Problem #4: I am changing my password using a web controller and DAO, why is my password still not being refreshed?

There are three things you must do to make a user password change take affect:

- Change the password using your authentication DAO
- Remove the user from the User Cache (i.e. if you have a cache configured)
- Update the `SecurityContextHolder` to include the new `Authentication` object and password

## I need some help. What files should I post?

The most important things to post with any support requests on the Spring Forums are your `web.xml`, `applicationContext.xml` (or whichever XML loads the security-related beans) as well as any custom `AuthenticationDao` you might be using. For really odd problems, also switch on debug-level logging and include the resulting log.

## How do I switch on debug-level logging?

Acegi Security uses Commons Logging, just as Spring does. So you use the same approach as you'd use for Spring. Most people output to Log4J, so the following `log4j.properties` would work:

    		log4j.rootCategory=WARN, stdout

    		log4j.appender.stdout=org.apache.log4j.ConsoleAppender
    		log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
    		log4j.appender.stdout.layout.ConversionPattern=%d %p %c - %m%n

    		log4j.category.net.sf.acegisecurity=DEBUG

## How do I store custom properties, like a user's email address?

In most cases write an `AuthenticationDao` which returns a subclass of `User`. Alternatively, write your own `UserDetails` implementation from scratch and return that.

## Why doesn't Acegi Security use JAAS?

Acegi Security targets enterprise applications, which are typically multi-user, data-oriented applications that are important to the core business. Acegi Security was designed to provide a portable and effective security framework for this target application type. It was not designed for securing limited privilege runtime environments, such as web browser applets.

We did consider JAAS when designing Acegi Security, but it simply wasn't suitable for our purpose. We needed to avoid complex JRE configurations, we needed container portability, and we wanted maximum leveraging of the Spring IoC container. Particularly as limited privilege runtime environments were not an actual requirement, this lead to the natural design of Acegi Security as it exists today.

Acegi Security already provides some JAAS integration. It can today authenticate via delegation to a JAAS login module. This means it offers the same level of JAAS integration as many web containers. Indeed the container adapter model supported by Acegi Security allows Acegi Security and container-managed security to happily co-exist and benefit from each other. Any debate about Acegi Security and JAAS should therefore centre on the authorisation issue. An evaluation of major containers and security frameworks would reveal that Acegi Security is by no means unusual in not using JAAS for authorisation.

There are many examples of open source applications being preferred to official standards. A few that come to mind in the Java community include using Spring managed POJOs (rather than EJBs), Hibernate (instead of entity beans), Log4J (instead of JDK logging), Tapestry (instead of JSF), and Velocity/FreeMarker (instead of JSP). It's important to recognise that many open source projects do develop into de facto standards, and in doing so play a legitimate and beneficial role in professional software development.

## Do you welcome contributions?

Yes. If you've written something and it works well, please feel free to share it. Simply email the contribution to the acegisecurity-developers list. If you haven't yet written the contribution, we encourage you to send your thoughts to the same list so that you can receive some initial design feedback.

For a contribution to be used, it must have appropriate unit test coverage and detailed JavaDocs. It will ideally have some comments for the Reference Guide as well (this can be sent in word processor or HTML format if desired). This helps ensure the contribution maintains the same quality as the remainder of the project.

We also welcome documentation improvements, unit tests, illustrations, people supporting the user community (especially on the forums), design ideas, articles, blog entries, presentations and alike. If you're looking for something to do, you can always email the acegisecurity-developers list and we'll be pleased to suggest something. :-)