From 118fde588c1c63aaec1270fe40eed13a4607620c Mon Sep 17 00:00:00 2001 From: Ben Alex Date: Wed, 22 Dec 2004 13:15:07 +0000 Subject: [PATCH] More documentation. --- doc/xdocs/articles.html | 64 ++++++++++++++++++ doc/xdocs/faq.html | 137 ++++++++++++++++++++++++++++++++++++++ doc/xdocs/navigation.xml | 20 +++--- doc/xdocs/reference.xml | 4 +- doc/xdocs/suggested.html | 138 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 351 insertions(+), 12 deletions(-) create mode 100644 doc/xdocs/articles.html create mode 100644 doc/xdocs/faq.html create mode 100644 doc/xdocs/suggested.html diff --git a/doc/xdocs/articles.html b/doc/xdocs/articles.html new file mode 100644 index 0000000000..e2c81f81fd --- /dev/null +++ b/doc/xdocs/articles.html @@ -0,0 +1,64 @@ + + + + + + +Articles, Blog Posts and Comments covering Acegi Security + + + + +

Articles, Blog Posts and Comments covering Acegi Security

+

Here are some of the external pages mentioning Acegi Security. If you've + found another, please let us know. +

+ + diff --git a/doc/xdocs/faq.html b/doc/xdocs/faq.html new file mode 100644 index 0000000000..51e229e74c --- /dev/null +++ b/doc/xdocs/faq.html @@ -0,0 +1,137 @@ + + + + + + +Frequently Asked Questions (FAQ) on Acegi Security + + + + +

Frequently Asked Questions

+ +

How do you pronounce "Acegi"?

+

Ah-see-gee. Said quickly, without emphasis on any part.

+ +

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.

+ +

Why 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 step from custom + AuthenticationDao implementations that simply don't properly + implement the interface. For example, they return null instead + of the user not found exception, or fail to add in the + GrantedAuthority[]s. We suggest you write the + UserDetails object generated by your AuthenticationDao + to the log and check it looks correct.

+ +

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.

+ +

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
+ +

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 the software development profession.

+ +

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. :-)

+ + + diff --git a/doc/xdocs/navigation.xml b/doc/xdocs/navigation.xml index a728569b3f..3519a25ba8 100644 --- a/doc/xdocs/navigation.xml +++ b/doc/xdocs/navigation.xml @@ -29,30 +29,30 @@ - - - - - - - - + + + + + + - + + + @@ -62,7 +62,7 @@ - + diff --git a/doc/xdocs/reference.xml b/doc/xdocs/reference.xml index 74963be47d..8a3545bdbd 100644 --- a/doc/xdocs/reference.xml +++ b/doc/xdocs/reference.xml @@ -39,7 +39,7 @@ The original docbook-generated reference. This is a good place to start if you want - to use the Acegi System to secure your applications. + to use the Acegi Security System to secure your applications. @@ -48,7 +48,7 @@ Reference Guide PDF - The pdf version of the reference guide. + The PDF version of the reference guide. diff --git a/doc/xdocs/suggested.html b/doc/xdocs/suggested.html new file mode 100644 index 0000000000..d9aba3d847 --- /dev/null +++ b/doc/xdocs/suggested.html @@ -0,0 +1,138 @@ + + + + + + +Acegi Security Suggested Steps + + + + +

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" 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. + +
  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 authorization 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. +

    + + Estimated time: 1-2 days.

    +
    3. + +
  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.

    +
    +
    4. + +
+ +

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. + +