From cf3cac90ad1deaed13c3abe4207abbf8e2feb99a Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Sun, 14 Dec 2008 23:53:44 +0000 Subject: [PATCH] SEC-1058, SEC-745: Updating comments --- .../security/ui/AbstractProcessingFilter.java | 149 +++++++++--------- ...onMappingAuthenticationFailureHandler.java | 2 + 2 files changed, 76 insertions(+), 75 deletions(-) diff --git a/core/src/main/java/org/springframework/security/ui/AbstractProcessingFilter.java b/core/src/main/java/org/springframework/security/ui/AbstractProcessingFilter.java index 7f1949cb86..0d129c79e7 100644 --- a/core/src/main/java/org/springframework/security/ui/AbstractProcessingFilter.java +++ b/core/src/main/java/org/springframework/security/ui/AbstractProcessingFilter.java @@ -15,32 +15,6 @@ package org.springframework.security.ui; -import org.springframework.security.SpringSecurityMessageSource; -import org.springframework.security.Authentication; -import org.springframework.security.AuthenticationException; -import org.springframework.security.AuthenticationManager; -import org.springframework.security.util.SessionUtils; -import org.springframework.security.util.UrlUtils; - -import org.springframework.security.concurrent.SessionRegistry; -import org.springframework.security.context.SecurityContextHolder; - -import org.springframework.security.event.authentication.InteractiveAuthenticationSuccessEvent; - -import org.springframework.security.ui.rememberme.NullRememberMeServices; -import org.springframework.security.ui.rememberme.RememberMeServices; -import org.springframework.security.ui.savedrequest.SavedRequest; - -import org.springframework.beans.factory.InitializingBean; - -import org.springframework.context.ApplicationEventPublisher; -import org.springframework.context.ApplicationEventPublisherAware; -import org.springframework.context.MessageSource; -import org.springframework.context.MessageSourceAware; -import org.springframework.context.support.MessageSourceAccessor; - -import org.springframework.util.Assert; - import java.io.IOException; import javax.servlet.FilterChain; @@ -49,60 +23,70 @@ import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.http.HttpSession; +import org.springframework.beans.factory.InitializingBean; +import org.springframework.context.ApplicationEventPublisher; +import org.springframework.context.ApplicationEventPublisherAware; +import org.springframework.context.MessageSource; +import org.springframework.context.MessageSourceAware; +import org.springframework.context.support.MessageSourceAccessor; +import org.springframework.security.Authentication; +import org.springframework.security.AuthenticationException; +import org.springframework.security.AuthenticationManager; +import org.springframework.security.SpringSecurityMessageSource; +import org.springframework.security.concurrent.SessionRegistry; +import org.springframework.security.context.SecurityContextHolder; +import org.springframework.security.event.authentication.InteractiveAuthenticationSuccessEvent; +import org.springframework.security.ui.rememberme.NullRememberMeServices; +import org.springframework.security.ui.rememberme.RememberMeServices; +import org.springframework.security.util.SessionUtils; +import org.springframework.security.util.UrlUtils; +import org.springframework.util.Assert; + /** * Abstract processor of browser-based HTTP-based authentication requests. - *

- * This filter is responsible for processing authentication requests. If - * authentication is successful, the resulting {@link Authentication} object - * will be placed into the SecurityContext, which is guaranteed - * to have already been created by an earlier filter. - *

- * If authentication fails, the AuthenticationException will be - * placed into the HttpSession with the attribute defined by - * {@link #SPRING_SECURITY_LAST_EXCEPTION_KEY}. - *

- * To use this filter, it is necessary to specify the following properties: - *

- *

- * To configure this filter to redirect to specific pages as the result of - * specific {@link AuthenticationException}s you can do the following. - * Configure the exceptionMappings property in your application - * xml. This property is a java.util.Properties object that maps a - * fully-qualified exception class name to a redirection url target. For - * example: * - * 

- *  <property name="exceptionMappings">
- *    <props>
- *      <prop> key="org.springframework.security.BadCredentialsException">/bad_credentials.jsp</prop>
- *    </props>
- *  </property>
- *
+ *

Authentication Process

* - * The example above would redirect all - * {@link org.springframework.security.BadCredentialsException}s thrown, to a page in the - * web-application called /bad_credentials.jsp. + * The filter requires that you set the authenticationManager property. An AuthenticationManager is + * required to process the authentication request tokens created by implementing classes. *

- * Any {@link AuthenticationException} thrown that cannot be matched in the - * exceptionMappings will be redirected to the - * authenticationFailureUrl + * This filter will intercept a request and attempt to perform authentication from that request if + * the request URL matches the value of the filterProcessesUrl property. This behaviour can modified by + * overriding the method {@link #requiresAuthentication(HttpServletRequest, HttpServletResponse) requiresAuthentication}. *

- * If authentication is successful, an {@link - * org.springframework.security.event.authentication.InteractiveAuthenticationSuccessEvent} - * will be published to the application context. No events will be published if - * authentication was unsuccessful, because this would generally be recorded via - * an AuthenticationManager-specific application event. + * Authentication is performed by the {@link #attemptAuthentication(HttpServletRequest, HttpServletResponse) + * attemptAuthentication} method, which must be implemented by subclasses. + * + *

Authentication Success

+ * + * If authentication is successful, the resulting {@link Authentication} object will be placed into the + * SecurityContext for the current thread, which is guaranteed to have already been created by an earlier + * filter. The configured {@link #setSuccessHandler(AuthenticationSuccessHandler) AuthenticationSuccessHandler} will + * then be called to take the redirect to the appropriate destination after a successful login. The default behaviour + * is implemented in a {@link SavedRequestAwareAuthenticationSuccessHandler} which will make use of any + * SavedRequest set by the ExceptionTranslationFilter and redirect the user to the URL contained + * therein. Otherwise it will redirect to the webapp root "/". You can customize this behaviour by injecting a + * differently configured instance of this class, or by using a different implementation. + *

+ * See the {@link #successfulAuthentication(HttpServletRequest, HttpServletResponse, Authentication) + * successfulAuthentication} method for more information. + * + *

Authentication Failure

+ * + * If authentication fails, the resulting AuthenticationException will be placed into the HttpSession + * with the attribute defined by {@link #SPRING_SECURITY_LAST_EXCEPTION_KEY}. It will then delegate to the configured + * {@link AuthenticationFailureHandler} to allow the failure information to be conveyed to the client. + * The default implementation is {@link SimpleUrlAuthenticationFailureHandler}, which sends a 401 error code to the + * client. It may also be configured with a failure URL as an alternative. Again you can inject whatever + * behaviour you require here. + * + *

Event Pulication

+ * + * If authentication is successful, an + * {@link org.springframework.security.event.authentication.InteractiveAuthenticationSuccessEvent + * InteractiveAuthenticationSuccessEvent} will be published via the application context. No events will be published if + * authentication was unsuccessful, because this would generally be recorded via an + * AuthenticationManager-specific application event. *

* The filter has an optional attribute invalidateSessionOnSuccessfulAuthentication that will invalidate * the current session on successful authentication. This is to protect against session fixation attacks (see @@ -320,9 +304,18 @@ public abstract class AbstractProcessingFilter extends SpringSecurityFilter impl successHandler.onAuthenticationSuccess(request, response, authResult); } + /** + * Default behaviour for unsuccessful authentication. + *

    + *
  1. Clears the {@link SecurityContextHolder}
    2. + *
  2. Stores the exception in the session (if it exists or allowSesssionCreation is set to true)
    3. + *
  3. Informs the configured RememberMeServices of the failed login
    4. + *
  4. Delegates additional behaviour to the {@link AuthenticationFailureHandler}.
    5. + *
+ */ protected void unsuccessfulAuthentication(HttpServletRequest request, HttpServletResponse response, AuthenticationException failed) throws IOException, ServletException { - SecurityContextHolder.getContext().setAuthentication(null); + SecurityContextHolder.clearContext(); if (logger.isDebugEnabled()) { logger.debug("Authentication request failed: " + failed.toString()); @@ -428,11 +421,17 @@ public abstract class AbstractProcessingFilter extends SpringSecurityFilter impl this.sessionRegistry = sessionRegistry; } + /** + * Sets the strategy used to handle a successful authentication. + * By default a {@link SavedRequestAwareAuthenticationSuccessHandler} is used. + */ public void setSuccessHandler(AuthenticationSuccessHandler successHandler) { + Assert.notNull(successHandler, "successHandler cannot be null"); this.successHandler = successHandler; } public void setFailureHandler(AuthenticationFailureHandler failureHandler) { + Assert.notNull(failureHandler, "failureHandler cannot be null"); this.failureHandler = failureHandler; } } diff --git a/core/src/main/java/org/springframework/security/ui/ExceptionMappingAuthenticationFailureHandler.java b/core/src/main/java/org/springframework/security/ui/ExceptionMappingAuthenticationFailureHandler.java index 5282206e80..78eb1fa8b8 100644 --- a/core/src/main/java/org/springframework/security/ui/ExceptionMappingAuthenticationFailureHandler.java +++ b/core/src/main/java/org/springframework/security/ui/ExceptionMappingAuthenticationFailureHandler.java @@ -19,6 +19,8 @@ import org.springframework.util.Assert; *

* If a match isn't found, falls back to the behaviour of the parent class, * {@link SimpleUrlAuthenticationFailureHandler}. + *

+ * The map of exception names to URLs should be injected by setting the exceptionMappings property. * * @author Luke Taylor * @version $Id$