Suggested Steps

Presented below are the steps we encourage you to take in order to gain the most out of Acegi Security in a realistic timeframe.

1. Your first step is to ensure you're able to actually build Acegi Security. This is because if you encounter any problems the first thing we'll probably suggest you do is upgrade to the latest CVS HEAD. It also means you can try things out if you get stuck, such as adding even more logging messages to the actual Acegi Security core code. The good news is building is actually very easy, and we've gone to a lot of trouble to document what is involved. If you have a working Maven installation, it should be as simple as two commands. Have a look on the Building with Maven page, and follow the "Checking Out from CVS", "Installing commons-attributes-plugin", and "Building All JARs" steps. Of course, you can safely skip this step if you don't have time.
   
   Estimated time: 30 minutes - 2 hours.
   
   
2. Next up gain a proper understanding of how the Contacts Sample application works. This will probably involve deploying acegi-security-sample-contacts-filter.war.
   
   The actual java code is a completely standard Spring application, except ContactManagerBackend which shows how we create and delete ACL permissions. The rest of the Java code has no security awareness, with all security services being declared in the XML files (don't worry, there aren't any new XML formats to learn: they're all standard Spring IoC container declarations or the stock-standard web.xml). The main XML files to review are applicationContext-acegi-security.xml (from the filter webapp), applicationContext-common-authorization.xml, applicationContext-common-business.xml (just note we add contactManagerSecurity to the services layer target bean), and web.xml (from the filter webapp). The XML definitions are comprehensively discussed in the Reference Guide.
   
   To gain the most from reviewing these XML files, we suggest you start by understanding how authentication takes place. There's not much point knowing all about authorisation until authentication is really clear, especially the interaction between the ContextHolder, the authentication mechanism (such as AuthenticationProcessingFilter), the authentication commencement process (specifically SecurityEnforcementFilter and say AuthenticationProcessingFilterEntryPoint), and the system that manages authentication data between invocations (say HttpSessionIntegrationFilter). You don't have to know every detail, just basically what they do and the key differences (again, the reference guide should help considerably, as there are diagrams etc).
   
   Once you understand authentication in the contacts Sample application, look at how authorisation is handled. Start with FilterSecurityInterceptor's role and how its regular expression or Ant paths protect URIs. Next up explore how RoleVoter works in our sample application with the FilterSecurityInterceptor and MethodSecurityInterceptor. Finally, review what the BasicAclEntryVoter does in our sample application, in terms of protecting domain objects from method invocations the principal does not have permission to.
   
   Lastly, get an understanding of how the AfterInvocationProviderManager is being used to stop domain objects being returned to which the principal has no permission, and to filter Collections so they don't contain domain objects to which the principal has no permission. By all means comment out parts of the Spring IoC XML and see the effect. For example, comment out the AfterInvocationProviderManager (of course, remove its reference in the MethodSecurityInterceptor) and see how all of the contacts get returned.
   
   Please note the release ZIP files do not include the sample application Java source code. You will need to download from CVS if you would like to access the Java sources.
   
   Estimated time: 1-2 days.
   
   
3. By now you will have a good grasp on how Acegi Security works, and all that is left to do is design your own application's implementation. The way we suggested you explore the Contacts Sample is the same way we suggest you implement security in your own application: start with authentication, then add basic web request URI security. Follow it with the standard role voter to protect method invocations. Finally, and only if your application actually needs it, introduce domain object security with the BasicAclEntryVoter and AfterInvocationProviderManager.
   
   We do not encourage you to use CAS, container adapters, BASIC authentication, transparent RMI invocation, run-as replacement, rich client integration or any of the other interesting features of Acegi Security until you've got a "bare bones" installation working with DaoAuthenticationProvider, one of Acegi Security's AuthenticationDaos (or your own), and your basic authorisation configuration. Like anything, start with something simple and build on it (this would be the opposite advice if you were building your own security framework, where you would need to cross the highest and most difficult bridges first, to check they are actually possible).
   
   If you've followed the steps above, and refer back to the Reference Guide, forums, and FAQ for help, you'll find it pretty easy to implement Acegi Security in your application. Most importantly, you'll be using a security framework that offers you complete container portability, flexibility, and community support - without needing to write and maintain your own code.
   
   Estimated time: 1-5 days.
   
   
   

Please note the time estimates are just that: estimates. They will vary considerably depending on how much experience you have, particularly with Java and Spring. They will also vary depending on how complex your intended security-enabled application will be. Some people need to push the domain object instance access control list capabilities to the maximum, whilst others don't even need anything beyond web request URI security. The good thing is Acegi Security will either directly support your future needs, or provide a clearly-defined extension point for addressing them.

We welcome your feedback about how long it has actually taken you to complete each step, so we can update this page and help new users better assess their project timetables in the future. Any other tips on what you found helpful in learning Acegi Security are also very welcome.