diff --git a/doc/docbook/acegi.xml b/doc/docbook/acegi.xml index 945940c31c..1fd583cbe8 100644 --- a/doc/docbook/acegi.xml +++ b/doc/docbook/acegi.xml @@ -885,20 +885,22 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { To secure FilterInvocations, developers need to add a filter to their web.xml that delegates to - the SecurityEnforcementFilter. A typical - configuration example is provided below: <filter> - <filter-name>Acegi HTTP Request Security Filter</filter-name> - <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class> - <init-param> - <param-name>targetClass</param-name> - <param-value>org.acegisecurity.intercept.web.SecurityEnforcementFilter</param-value> - </init-param> -</filter> + the FilterSecurityInterceptor. A typical + configuration example is provided below: + Acegi HTTP Request Security Filter + org.acegisecurity.util.FilterToBeanProxy + + targetClass + org.acegisecurity.intercept.web.FilterSecurityInterceptor + + -<filter-mapping> - <filter-name>Acegi HTTP Request Security Filter</filter-name> - <url-pattern>/*</url-pattern> -</filter-mapping> + + Acegi HTTP Request Security Filter + /* + +]]> Notice that the filter is actually a FilterToBeanProxy. Most of the filters used by the @@ -908,29 +910,48 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { In the application context you will need to configure three beans: - <bean id="securityEnforcementFilter" class="org.acegisecurity.intercept.web.SecurityEnforcementFilter"> - <property name="filterSecurityInterceptor"><ref bean="filterInvocationInterceptor"/></property> - <property name="authenticationEntryPoint"><ref bean="authenticationEntryPoint"/></property> -</bean> + + + -<bean id="authenticationEntryPoint" class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint"> - <property name="loginFormUrl"><value>/acegilogin.jsp</value></property> - <property name="forceHttps"><value>false</value></property> -</bean> - -<bean id="filterInvocationInterceptor" class="org.acegisecurity.intercept.web.FilterSecurityInterceptor"> - <property name="authenticationManager"><ref bean="authenticationManager"/></property> - <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property> - <property name="runAsManager"><ref bean="runAsManager"/></property> - <property name="objectDefinitionSource"> - <value> + + /acegilogin.jsp + false + + + + + + + CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON \A/secure/super/.*\Z=ROLE_WE_DONT_HAVE \A/secure/.*\Z=ROLE_SUPERVISOR,ROLE_TELLER - </value> - </property> -</bean> + + + +]]> + + + The ExceptionTranslationFilter + provides the bridge between Java exceptions and HTTP responses. + It is solely concerned with maintaining the + user interface. This filter does not do any actual security enforcement. + If an AuthenticationException is detected, + the filter will call the AuthenticationEntryPoint to commence the + authentication process (e.g. a user login). + + The AuthenticationEntryPoint will be called if the user requests a secure HTTP resource but they are not authenticated. The class handles presenting the appropriate response @@ -945,28 +966,15 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { AuthenticationProcessingFilterEntryPoint and CasProcessingFilterEntryPoint have optional properties related to forcing the use of HTTPS, so please refer to the - JavaDocs if you require this. - - The PortMapper provides information on which - HTTPS ports correspond to which HTTP ports. This is used by the - AuthenticationProcessingFilterEntryPoint and - several other beans. The default implementation, - PortMapperImpl, knows the common HTTP ports 80 and - 8080 map to HTTPS ports 443 and 8443 respectively. You can customise - this mapping if desired. - - The SecurityEnforcementFilter primarily - provides session management support and initiates authentication when - required. It delegates actual FilterInvocation - security decisions to the configured - FilterSecurityInterceptor. - - Like any other security interceptor, the - FilterSecurityInterceptor requires a reference to - an AuthenticationManager, - AccessDecisionManager and - RunAsManager, which are each discussed in separate - sections below. The FilterSecurityInterceptor is + JavaDocs if you require this. + + FilterSecurityInterceptor is responsible for + handling the security of HTTP resources. + Like any other security + interceptor, it requires a reference to an AuthenticationManager + and an AccessDecisionManager, which are both + discussed in separate sections below. The + FilterSecurityInterceptor is also configured with configuration attributes that apply to different HTTP URL requests. A full discussion of configuration attributes is provided in the High Level Design section of this document. @@ -1760,7 +1768,7 @@ public aspect DomainObjectInstanceSecurityAspect implements InitializingBean { <value> CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON PATTERN_TYPE_APACHE_ANT - /**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,securityEnforcementFilter + /**=httpSessionContextIntegrationFilter,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor </value> </property> </bean> @@ -2593,7 +2601,7 @@ public boolean supports(Class clazz); attribute specified by AbstractProcessingFilter.ACEGI_SECURITY_TARGET_URL_KEY. This attribute is automatically set by the - SecurityEnforcementFilter when an + ExceptionTranslationFilter when an AuthenticationException occurs, so that after login is completed the user can return to what they were trying to access. If for some reason the HttpSession does not @@ -2862,7 +2870,7 @@ key: A private key to prevent modification of the nonce token isAnonymous(Authentication) method, which allows interested classes to take into account this special type of authentication status. The - SecurityEnforcementFilter uses this interface in + ExceptionTranslationFilter uses this interface in processing AccessDeniedExceptions. If an AccessDeniedException is thrown, and the authentication is of an anonymous type, instead of throwing a 403 @@ -3516,7 +3524,7 @@ $CATALINA_HOME/bin/startup.sh The user eventually requests a page that is either secure or one of the beans it uses is secure. Acegi Security's - SecurityEnforcementFilter will detect the + ExceptionTranslationFilter will detect the AuthenticationException. @@ -3524,7 +3532,7 @@ $CATALINA_HOME/bin/startup.sh Because the user's Authentication object (or lack thereof) caused an AuthenticationException, the - SecurityEnforcementFilter will call the + ExceptionTranslationFilter will call the configured AuthenticationEntryPoint. If using CAS, this will be the CasProcessingFilterEntryPoint class. @@ -3815,22 +3823,24 @@ $CATALINA_HOME/bin/startup.sh The following beans should be configured to commence the CAS authentication process: - <bean id="casProcessingFilter" class="org.acegisecurity.ui.cas.CasProcessingFilter"> - <property name="authenticationManager"><ref bean="authenticationManager"/></property> - <property name="authenticationFailureUrl"><value>/casfailed.jsp</value></property> - <property name="defaultTargetUrl"><value>/</value></property> - <property name="filterProcessesUrl"><value>/j_acegi_cas_security_check</value></property> -</bean> + + + /casfailed.jsp + / + /j_acegi_cas_security_check + -<bean id="securityEnforcementFilter" class="org.acegisecurity.intercept.web.SecurityEnforcementFilter"> - <property name="filterSecurityInterceptor"><ref bean="filterInvocationInterceptor"/></property> - <property name="authenticationEntryPoint"><ref bean="casProcessingFilterEntryPoint"/></property> -</bean> + + + -<bean id="casProcessingFilterEntryPoint" class="org.acegisecurity.ui.cas.CasProcessingFilterEntryPoint"> - <property name="loginUrl"><value>https://localhost:8443/cas/login</value></property> - <property name="serviceProperties"><ref bean="serviceProperties"/></property> -</bean> + + https://localhost:8443/cas/login + + +]]> + You will also need to add the CasProcessingFilter to web.xml: @@ -3855,7 +3865,7 @@ $CATALINA_HOME/bin/startup.sh self-explanatory. For CAS to operate, the - SecurityEnforcementFilter must have its + ExceptionTranslationFilter must have its authenticationEntryPoint property set to the CasProcessingFilterEntryPoint bean. @@ -4106,7 +4116,7 @@ $CATALINA_HOME/bin/startup.sh valid Authentication object in the secure context and the invocation will procede as normal. If no certificate was found, or the certificate was rejected, then the - SecurityEnforcementFilter will invoke the + ExceptionTranslationFilter will invoke the X509ProcessingFilterEntryPoint which returns a 403 error (forbidden) to the user. @@ -5099,14 +5109,14 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); <value> CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON PATTERN_TYPE_APACHE_ANT - /webServices/**=httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,securityEnforcementFilter - /**=httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,securityEnforcementFilter + /webServices/**=httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor + /**=httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor </value> </property> </bean> You may notice similarities with the way - SecurityEnforcementFilter is declared. Both regular + FilterSecurityInterceptor is declared. Both regular expressions and Ant Paths are supported, and the most specific URIs appear first. At runtime the FilterChainProxy will locate the first URI pattern that matches the current web request. @@ -5117,10 +5127,10 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); Filter can elect not to proceed with the chain if it wishes to end processing). - As you can see, FitlerChainProxy requires the + As you can see, FilterChainProxy requires the duplication of filter names for different request patterns (in the - above example, httpSessionContextIntegrationFilter - and securityEnforcementFilter are duplicated). This + above example, exceptionTranslationFilter + and filterSecurityInterceptor are duplicated). This design decision was made to enable FilterChainProxy to specify different Filter invocation orders for different URI patterns, and also to improve both the expressiveness @@ -5229,10 +5239,15 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); - SecurityEnforcementFilter, to protect web - URIs and catch any Acegi Security exceptions so that an - appropriate AuthenticationEntryPoint can be - launched + ExceptionTranslationFilter, catch any Acegi Security + exceptions so that an either an HTTP error response can be returned + or an appropriate AuthenticationEntryPoint + can be launched + + + + FilterSecurityInterceptor, to protect web + URIs @@ -5334,7 +5349,7 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); requests. If using either of these WARs, be sure to try visiting http://localhost:8080/contacts/secure/super, which will demonstrate access being denied by the - SecurityEnforcementFilter. Note the sample + FilterSecurityInterceptor. Note the sample application enables you to modify the access control lists associated with different contacts. Be sure to give this a try and understand how it works by reviewing the sample application's application context XML