From c8055b57d70101be40770a058a8ed47c7770bbcd Mon Sep 17 00:00:00 2001 From: Ben Alex Date: Thu, 23 Dec 2004 00:15:00 +0000 Subject: [PATCH] More documentation updates. --- doc/xdocs/articles.html | 24 ++++----- doc/xdocs/faq.html | 111 ++++++++++++++++++++++++++++++++++++--- doc/xdocs/index.html | 48 ++++++++++------- doc/xdocs/navigation.xml | 17 +++--- doc/xdocs/suggested.html | 9 ++-- 5 files changed, 159 insertions(+), 50 deletions(-) diff --git a/doc/xdocs/articles.html b/doc/xdocs/articles.html index e2c81f81fd..7644944a6c 100644 --- a/doc/xdocs/articles.html +++ b/doc/xdocs/articles.html @@ -22,42 +22,42 @@ -Articles, Blog Posts and Comments covering Acegi Security +External Web Articles covering Acegi Security -

Articles, Blog Posts and Comments covering Acegi Security

+

External Web Articles 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 index 51e229e74c..3927e9300d 100644 --- a/doc/xdocs/faq.html +++ b/doc/xdocs/faq.html @@ -29,8 +29,105 @@

Frequently Asked Questions

+

What is Acegi Security?

+

Acegi Security is an open source project that provide 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 assuming 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. +
  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 request + 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. +
  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. +
    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. +
    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 e + conomical (on a cost-benefit basis) to simply use a dedicated + security framework.
      4. +
    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. +
    +
    4. +
+ For simple applications, servlet specification 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.

+

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, @@ -39,7 +136,7 @@ as that gets confused with the name of the company that maintains Acegi Security.

-

Why catches 80% of users reporting problems?

+

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 @@ -55,11 +152,6 @@ 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 @@ -82,6 +174,11 @@ 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 diff --git a/doc/xdocs/index.html b/doc/xdocs/index.html index 5f1cc0e055..e4f6326a9f 100644 --- a/doc/xdocs/index.html +++ b/doc/xdocs/index.html @@ -25,10 +25,8 @@ href="http://apr.apache.org/versioning.html">Apache APR Project Versioning Guidelines so you can identify backward compatibility.

-

  • Easy to use: View our samples/quick-start directory for XML - you can simply copy and paste into applicationContext.xml and web.xml. - From there it's easy to customise Acegi Security to your unique security - needs.

    +
  • Fast results: View our Suggested Steps + for the fastest way to develop complex, security-compliant applications.

  • Enterprise-wide single sign on: Using Yale University's open source Central Authentication Service (CAS), the Acegi Security System for Spring can participate @@ -61,6 +59,11 @@ parameter on method being invoked....). This package gives you this flexibility without adding security code to your Spring business objects.

    +
  • After invocation security: Acegi Security can not only protect + methods from being invoked in the first place, but it can also + deal with the Objects returned from the methods. Included implementations + of after invocation security can throw an exception or mutate the returned + object based on ACLs.

  • Secures your HTTP requests as well: In addition to securing your beans, the project also secures your HTTP requests. No longer is it necessary to rely on web.xml security constraints. Best of all, your @@ -81,7 +84,8 @@ BASIC authentication requests as per RFC 1945.

  • Convenient security taglib: Your JSP files can use our taglib to ensure that protected content like links and messages are only - displayed to users holding the appropriate granted authorities.

    + displayed to users holding the appropriate granted authorities. The taglib + also fully integrates with Acegi Security's ACL services.

  • Application context or attribute-based configuration: You select the method used to configure your security environment. The project supports configuration via Spring application contexts as well @@ -93,15 +97,15 @@ anywhere you like.

  • Event support: Building upon Spring's ApplicationEvent services, you can write your own listeners - for login, invalid password and account disabled events. This enables - you to implement account lockout and audit log systems, with complete - decoupling from Acegi Security code.

    + for authentication-related events, along with authorisation-related events. + This enables you to implement account lockout and audit log systems, with + complete decoupling from Acegi Security code.

  • Easy integration with existing databases: Our implementations have been designed to make it very easy to use your existing - authentication schema and data (without modification).

    -
  • Caching: Use our EHCACHE wrapper to cache your - authentication information, or plug in your own cache implementation. + authentication schema and data (without modification). Of course, + you can also provide your own Data Access Object if you wish.

    +
  • Caching: Acegi Security integrates with Spring's EHCACHE factory. This flexibility means your database (or other authentication repository) is not repeatedly queried for authentication information.

    @@ -127,13 +131,18 @@ request or bean invocation. This enables you to build public-facing object tiers with different security configurations than your backend objects.

    +
  • Transparent security propagation: Acegi Security can automatically + transfer its core authentication information from one machine to another, + using a variety of protocols including RMI and Spring's HttpInvoker.

    +
  • Compatible with HttpServletRequest.getRemoteUser(): Even though + Acegi Security can deliver authentication using a range of pluggable mechanisms + (most of which require no web container configuration), we allow you to access + the resulting Authentication object via the getRemoteUser() method.

  • Unit tests: A must-have of any quality security project, unit - tests are included. Clover coverage is currently 98.3%.

    -
  • Container integration tests: To ensure the security project - properly operates with major container versions, we provide an - integration test system that deploys those containers from scratch and - fully tests our sample web application from the perspective of a HTTP - client.

    + tests are included. Our unit test coverage is very high, as shown in the + coverage report.

    +
  • Built by Maven: This assists you in effectively reusing the Acegi + Security artifacts in your own Maven-based projects.

  • Supports your own unit tests: We provide a number of classes that assist with your own unit testing of secured business objects. For example, you can change the authentication identity and its associated @@ -143,7 +152,8 @@ and code quality improvements that emerge from peer review.

  • Thorough documentation: All APIs are fully documented using JavaDoc, with a 40+ page reference guide providing an easy-to-follow - introduction.

    + introduction. More documentation is provided on this web site, as + shown in the left hand navigation sidebar.

  • Apache license.


    • diff --git a/doc/xdocs/navigation.xml b/doc/xdocs/navigation.xml index 3519a25ba8..ee0bf187bc 100644 --- a/doc/xdocs/navigation.xml +++ b/doc/xdocs/navigation.xml @@ -30,14 +30,14 @@ - + - + @@ -46,13 +46,12 @@ - - - - - - - + + + + + + diff --git a/doc/xdocs/suggested.html b/doc/xdocs/suggested.html index d9aba3d847..b8183c78dc 100644 --- a/doc/xdocs/suggested.html +++ b/doc/xdocs/suggested.html @@ -56,7 +56,7 @@ 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-authorisation.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 @@ -64,7 +64,7 @@

    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 + 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 @@ -111,7 +111,10 @@ 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 + 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