diff --git a/doc/docbook/acegi.xml b/doc/docbook/acegi.xml index 6cd0d54619..60cfd6cdd7 100644 --- a/doc/docbook/acegi.xml +++ b/doc/docbook/acegi.xml @@ -342,51 +342,61 @@ ContextHolder was used will likely mean that certain documentation you encounter concerning Acegi Security might still refer to ContextHolder. Generally you can - just substitute "SecurityContext" for - "ContextHolder" and you'll have the primary meaning - of such documentation. + just substitute "SecurityContextHolder" for + "ContextHolder", and + "SecurityContext" for + "SecureContext", and you'll have the primary + meaning of such documentation. SecurityContext The Acegi Security System for Spring uses a - SecurityContext to store the + SecurityContextHolder to store the + SecurityContext. The + SecurityContext contains a single getter/setter for Authentication. All Acegi Security classes query - the SecurityContext for obtaining the currently - principal. SecurityContext is an + the SecurityContextHolder for obtaining the current + SecurityContext (and in turn the principal). + SecurityContextHolder is an InheritableThreadLocal, meaning it is associated - with the current thread of execution. - SecurityContext simply provides a single getter and - setter pair for the Authentication object. + with the current thread of execution. Context Storage Central to Acegi Security's design is that the contents of the - SecurityContext (which is simply an - Authentication object) can be stored between web - requests. This is so that a successfully authenticated principal can - be identified on subsequent requests through the - Authentication stored inside a - SecurityContext. The + SecurityContextHolder (which is simply a + SecurityContext implementation) can be stored + between web requests. This is so that a successfully authenticated + principal can be identified on subsequent requests through the + Authentication stored inside the + SecurityContext obtained from the + SecurityContextHolder. The HttpSessionContextIntegrationFilter exists to automatically copy the contents of a well-defined HttpSession attribute into the - SecurityContext, then at the end of each request, - copy the SecurityContext contents back into the - HttpSession ready for next request. + SecurityContextHolder, then at the end of each + request, copy the SecurityContextHolder contents + back into the HttpSession ready for next + request. It is essential - and an extremely common error of end users - that HttpSessionContextIntegrationFilter appears before any other Acegi Security filter. Acegi Security filters expect - to be able to modify the SecurityContext contents - as they see fit, and something else (namely + to be able to modify the SecurityContextHolder + contents as they see fit, and something else (namely HttpSessionContextIntegrationFilter) will store those between requests if necessary. This is why HttpSessionContextIntegrationFilter must be the first filter used. + + You can define a custom SecurityContext + implementation be used in your application by setting the + context property on the + HttpSessionContextIntegrationFilter bean.