概述

该过滤器会拦截用户请求，看它是否是一个来自用户名/密码表单登录页面提交的用户登录认证请求，缺省使用的匹配模式是:POST /login。缺省情况下，如果是用户登录认证请求，该请求就不会在整个filter chain中继续传递了，而是会被当前过滤器处理并进入响应用户阶段。

具体用户登录认证处理逻辑是这样的，它会调用所指定的AuthenticationManager认证所提交的用户名/密码。

如果认证成功，则会 ：

1. 调用所设置的SessionAuthenticationStrategy会话认证策略;

   针对Servlet 3.1+,缺省所使用的SessionAuthenticationStrategy是一个ChangeSessionIdAuthenticationStrategy和CsrfAuthenticationStrategy组合。ChangeSessionIdAuthenticationStrategy会为登录的用户创建一个新的session，而CsrfAuthenticationStrategy会创建新的csrf token用于CSRF保护。

2. 经过完全认证的Authentication对象设置到SecurityContextHolder中的SecurityContext上;

3. 如果请求要求了Remember Me,进行相应记录;

4. 发布事件InteractiveAuthenticationSuccessEvent;

5. 获取并跳转到目标跳转页面；

   缺省情况下，该跳转策略是SavedRequestAwareAuthenticationSuccessHandler。

   • 如果有保存的请求,则获取保存的请求，跳转到相应的请求地址;
     

     一般在未登录用户直接访问受保护页面时会出现该情况：先被跳转到登录页面，登录完成过后再被跳转到原始请求页面

   • alwaysUseDefaultTargetUrl为true则总是会跳到指定的defaultTargetUrl;
     

     注意: defaultTargetUrl 也是可以设置的，如果不设置，其值缺省为/

   • alwaysUseDefaultTargetUrl为false则
     • 看请求参数中是否含有名称为配置参数targetUrlParameter值的参数，如果有，跳转到它定义的地址；
     • 否则如果指定了useReferer，尝试使用请求头部Referer作为目标跳转地址;
     • 否则使用defaultTargetUrl作为目标跳转地址;

源代码解析

package org.springframework.security.web.authentication;

import org.springframework.security.authentication.AuthenticationServiceException;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.web.util.matcher.AntPathRequestMatcher;
import org.springframework.util.Assert;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class UsernamePasswordAuthenticationFilter extends
        AbstractAuthenticationProcessingFilter {
    // ~ Static fields/initializers
    // =====================================================================================

    // 用户名/密码登录表单中用户名字段缺省使用的名称
    public static final String SPRING_SECURITY_FORM_USERNAME_KEY = "username";
    // 用户名/密码登录表单中密码字段缺省使用的名称
    public static final String SPRING_SECURITY_FORM_PASSWORD_KEY = "password";

    private String usernameParameter = SPRING_SECURITY_FORM_USERNAME_KEY;
    private String passwordParameter = SPRING_SECURITY_FORM_PASSWORD_KEY;
    private boolean postOnly = true;

    // ~ Constructors
    // ===================================================================================================

    public UsernamePasswordAuthenticationFilter() {
        // 缺省匹配用户请求 POST /login，认为该请求是用户名/密码表单登录验证请求
        super(new AntPathRequestMatcher("/login", "POST"));
    }

    // ~ Methods
    // ========================================================================================================

    public Authentication attemptAuthentication(HttpServletRequest request,
            HttpServletResponse response) throws AuthenticationException {
        if (postOnly && !request.getMethod().equals("POST")) {
            throw new AuthenticationServiceException(
                    "Authentication method not supported: " + request.getMethod());
        }

        // 从请求中获取用户名/密码，也就是用户填写在用户名/密码登录表单中的这些信息
        String username = obtainUsername(request);
        String password = obtainPassword(request);

        if (username == null) {
            username = "";
        }

        if (password == null) {
            password = "";
        }

        // 注意，这里对用户名做了trim操作，一般理解，就是去除了前后的空格
        username = username.trim();

        // 根据用户提供的用户名/密码信息构建一个认证token
        UsernamePasswordAuthenticationToken authRequest = new UsernamePasswordAuthenticationToken(
                username, password);

        // Allow subclasses to set the "details" property
        setDetails(request, authRequest);

        // 交给 authenticationManager执行真正的用户身份认证
        return this.getAuthenticationManager().authenticate(authRequest);
    }

    /** * 从请求参数中获取密码 * * Enables subclasses to override the composition of the password, such as by * including additional values and a separator. * * This might be used for example if a postcode/zipcode was required in addition to * the password. A delimiter such as a pipe (|) should be used to separate the * password and extended value(s). The AuthenticationDao will need to * generate the expected password in a corresponding manner. * * * @param request so that request attributes can be retrieved * * @return the password that will be presented in the Authentication * request token to the AuthenticationManager */
    protected String obtainPassword(HttpServletRequest request) {
        return request.getParameter(passwordParameter);
    }

    /** * 从请求参数中获取用户名 * * Enables subclasses to override the composition of the username, such as by * including additional values and a separator. * * @param request so that request attributes can be retrieved * * @return the username that will be presented in the Authentication * request token to the AuthenticationManager */
    protected String obtainUsername(HttpServletRequest request) {
        return request.getParameter(usernameParameter);
    }

    /** * Provided so that subclasses may configure what is put into the authentication * request's details property. * * @param request that an authentication request is being created for * @param authRequest the authentication request object that should have its details * set */
    protected void setDetails(HttpServletRequest request,
            UsernamePasswordAuthenticationToken authRequest) {
        authRequest.setDetails(authenticationDetailsSource.buildDetails(request));
    }

    /** * Sets the parameter name which will be used to obtain the username from the login * request. * 指定从用户名/密码登录认证表单中获取用户名时使用的属性名称，缺省为 username * @param usernameParameter the parameter name. Defaults to "username". */
    public void setUsernameParameter(String usernameParameter) {
        Assert.hasText(usernameParameter, "Username parameter must not be empty or null");
        this.usernameParameter = usernameParameter;
    }

    /** * Sets the parameter name which will be used to obtain the password from the login * request.. * 指定从用户名/密码登录认证表单中获取用户名时使用的属性名称，缺省为 password * @param passwordParameter the parameter name. Defaults to "password". */
    public void setPasswordParameter(String passwordParameter) {
        Assert.hasText(passwordParameter, "Password parameter must not be empty or null");
        this.passwordParameter = passwordParameter;
    }

    /** * Defines whether only HTTP POST requests will be allowed by this filter. If set to * true, and an authentication request is received which is not a POST request, an * exception will be raised immediately and authentication will not be attempted. The * unsuccessfulAuthentication() method will be called as if handling a failed * authentication. * * 设置是否仅仅接受HTTP POST用户名/密码登录验证表单请求，缺省为true，表示必须使用HTTP POST。 * * Defaults to true but may be overridden by subclasses. */
    public void setPostOnly(boolean postOnly) {
        this.postOnly = postOnly;
    }

    public final String getUsernameParameter() {
        return usernameParameter;
    }

    public final String getPasswordParameter() {
        return passwordParameter;
    }
}

UsernamePasswordAuthenticationFilter继承自AbstractAuthenticationProcessingFilter:

package org.springframework.security.web.authentication;

import java.io.IOException;

import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

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.AuthenticationDetailsSource;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.InternalAuthenticationServiceException;
import org.springframework.security.authentication.event.InteractiveAuthenticationSuccessEvent;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.core.SpringSecurityMessageSource;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.session.NullAuthenticatedSessionStrategy;
import org.springframework.security.web.authentication.session.SessionAuthenticationStrategy;
import org.springframework.security.web.util.matcher.AntPathRequestMatcher;
import org.springframework.security.web.util.matcher.RequestMatcher;
import org.springframework.util.Assert;
import org.springframework.web.filter.GenericFilterBean;

/** * Abstract processor of browser-based HTTP-based authentication requests. * 基于浏览器和HTTP的认证请求的处理抽象。 * * Authentication Process 认证过程 * * The filter requires that you set the authenticationManager property. An * AuthenticationManager is required to process the authentication request tokens * created by implementing classes. * 该过滤器执行认证需要一个authenticationManager，这个AuthenticationManager用来针对 * 所创建的认证请求token做真正的用户身份认证动作。 * * This filter will intercept a request and attempt to perform authentication from that * request if the request matches the * #setRequiresAuthenticationRequestMatcher(RequestMatcher). * 该过滤器拦截请求识别当前请求是否一个用户名/密码表单认证请求的匹配方法是通过方法 * #setRequiresAuthenticationRequestMatcher(RequestMatcher)指定的一个RequestMatcher。 * * Authentication is performed by the * #attemptAuthentication(HttpServletRequest, HttpServletResponse) * method, which must be implemented by subclasses. * 认证动作由方法#attemptAuthentication(HttpServletRequest, HttpServletResponse)完成， * 该方法由子类实现。上面的UsernamePasswordAuthenticationFilter就提供了该方法的实现。 * * Authentication Success 认证成功 * * If authentication is successful, the resulting Authentication object will be * placed into the SecurityContext for the current thread, which is * guaranteed to have already been created by an earlier filter. * 认证成功时，结果认证对象Authentication会被放到一个SecurityContext对象中，然后保存在处理 * 当前请求的线程中。 * * The configured #setAuthenticationSuccessHandler(AuthenticationSuccessHandler) * will then be called to take the redirect to the * appropriate destination after a successful login. The default behaviour is implemented * in a SavedRequestAwareAuthenticationSuccessHandler which will make use of any * DefaultSavedRequest 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. * 然后通过#setAuthenticationSuccessHandler(AuthenticationSuccessHandler)所设置的 * AuthenticationSuccessHandler会被调用，从而页面被跳转到所配置的成功登录页面。 * * Authentication Failure 认证失败 * * If authentication fails, it will delegate to the configured * AuthenticationFailureHandler to allow the failure information to be conveyed to * the client. The default implementation is 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. * 如果认证失败，该过滤器会代理给AuthenticationFailureHandler将失败信息传回给客户。缺省实现是 * 一个SimpleUrlAuthenticationFailureHandler，它会发送一个HTTP 401代码给客户端。 * * Event Publication 事件发布 * * If authentication is successful, an 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. * 认证成功时一个InteractiveAuthenticationSuccessEvent事件会发布到应用上下文。认证不成功 * 则不会发布任何事件。 * * Session Authentication * * The class has an optional SessionAuthenticationStrategy which will be invoked * immediately after a successful call to attemptAuthentication(). Different * implementations * #setSessionAuthenticationStrategy(SessionAuthenticationStrategy) can be * injected to enable things like session-fixation attack prevention or to control the * number of simultaneous sessions a principal may have. * * @author Ben Alex * @author Luke Taylor */
public abstract class AbstractAuthenticationProcessingFilter extends GenericFilterBean
        implements ApplicationEventPublisherAware, MessageSourceAware {
    // ~ Static fields/initializers
    // =====================================================================================

    // ~ Instance fields
    // ================================================================================================

    protected ApplicationEventPublisher eventPublisher;
    protected AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource = 
        new WebAuthenticationDetailsSource();
    // 真正执行认证的认真管理器
    private AuthenticationManager authenticationManager;
    protected MessageSourceAccessor messages = SpringSecurityMessageSource.getAccessor();
    private RememberMeServices rememberMeServices = new NullRememberMeServices();

    private RequestMatcher requiresAuthenticationRequestMatcher;

    // 登录认证成功时是否继续执行filter chain，缺省为false，该属性安全配置阶段会重新指定,
    // 但安全配置阶段缺省使用的值也是false，表示登录认证成功时不继续执行filter chain，而是
    // 由该页面直接进入响应用户阶段
    private boolean continueChainBeforeSuccessfulAuthentication = false;

    // session 认证策略
    // 安全配置中缺省是一个 CompositeSessionAuthenticationStrategy 对象，应用了组合模式，组合一些其他的
    // session 认证策略实现，比如针对Servlet 3.1+,缺省会是 ChangeSessionIdAuthenticationStrategy跟
    // CsrfAuthenticationStrategy组合
    // 这里虽然初始化为NullAuthenticatedSessionStrategy,但它会被安全配置中的值覆盖
    private SessionAuthenticationStrategy sessionStrategy = new NullAuthenticatedSessionStrategy();

    private boolean allowSessionCreation = true;

    private AuthenticationSuccessHandler successHandler = new SavedRequestAwareAuthenticationSuccessHandler();
    private AuthenticationFailureHandler failureHandler = new SimpleUrlAuthenticationFailureHandler();

    // ~ Constructors
    // ===================================================================================================

    /** * @param defaultFilterProcessesUrl the default value for <tt>filterProcessesUrl</tt>. */
    protected AbstractAuthenticationProcessingFilter(String defaultFilterProcessesUrl) {
        setFilterProcessesUrl(defaultFilterProcessesUrl);
    }

    /** * Creates a new instance * * @param requiresAuthenticationRequestMatcher the {@link RequestMatcher} used to * determine if authentication is required. Cannot be null. */
    protected AbstractAuthenticationProcessingFilter(
            RequestMatcher requiresAuthenticationRequestMatcher) {
        Assert.notNull(requiresAuthenticationRequestMatcher,
                "requiresAuthenticationRequestMatcher cannot be null");
        this.requiresAuthenticationRequestMatcher = requiresAuthenticationRequestMatcher;
    }

    // ~ Methods
    // ========================================================================================================

    @Override
    public void afterPropertiesSet() {
        Assert.notNull(authenticationManager, "authenticationManager must be specified");
    }


    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {

        HttpServletRequest request = (HttpServletRequest) req;
        HttpServletResponse response = (HttpServletResponse) res;

        if (!requiresAuthentication(request, response)) {
            // 检查当前请求是否是一个用户名/密码登录表单请求，如果不是，则继续执行filter chain
            // 的其他部分
            chain.doFilter(request, response);

            return;
        }

        // 下面是检测到这是一个用户名/密码登录表单请求时的处理逻辑
        if (logger.isDebugEnabled()) {
            logger.debug("Request is to process authentication");
        }

        Authentication authResult;

        try {
            // 交给 AuthenticationManger 执行相应的认证
            authResult = attemptAuthentication(request, response);
            if (authResult == null) {
                // return immediately as subclass has indicated that it hasn't completed
                // authentication
                return;
            }
            //针对Servlet 3.1+,缺省所使用的SessionAuthenticationStrategy会是一个
            //ChangeSessionIdAuthenticationStrategy和CsrfAuthenticationStrategy组合。
            //ChangeSessionIdAuthenticationStrategy会为登录的用户创建一个新的session，
            //而CsrfAuthenticationStrategy会创建新的csrf token用于CSRF保护。
            sessionStrategy.onAuthentication(authResult, request, response);
        }
        catch (InternalAuthenticationServiceException failed) {
            logger.error(
                    "An internal error occurred while trying to authenticate the user.",
                    failed);
            // 认证失败 
            unsuccessfulAuthentication(request, response, failed);

            return;
        }
        catch (AuthenticationException failed) {
            // Authentication failed
            // 认证失败
            unsuccessfulAuthentication(request, response, failed);

            return;
        }

        // Authentication success
        // 认证成功，如果continueChainBeforeSuccessfulAuthentication为true，
        // (continueChainBeforeSuccessfulAuthentication缺省为false)
        // 继续执行filter chain的其他部分
        if (continueChainBeforeSuccessfulAuthentication) {
            chain.doFilter(request, response);
        }

        // 认证成功后的处理逻辑
        successfulAuthentication(request, response, chain, authResult);
    }

    /** * 检测当前请求是否是登录认证请求 * Indicates whether this filter should attempt to process a login request for the * current invocation. * * It strips any parameters from the "path" section of the request URL (such as the * jsessionid parameter in http://host/myapp/index.html;jsessionid=blah) * before matching against the filterProcessesUrl property. * * Subclasses may override for special requirements, such as Tapestry integration. * * @return true if the filter should attempt authentication, * false otherwise. */
    protected boolean requiresAuthentication(HttpServletRequest request,
            HttpServletResponse response) {
        return requiresAuthenticationRequestMatcher.matches(request);
    }

    /** * Performs actual authentication. 执行真正的认证 * * The implementation should do one of the following: * 会是以下三种情况之一: * * 1.Return a populated authentication token for the authenticated user, indicating * successful authentication 认证成功，填充认证了的用户的其他信息到authentication token并返回之 * 2.Return null, indicating that the authentication process is still in progress. * Before returning, the implementation should perform any additional work required to * complete the process.返回null表示认证仍在进行中。 * 3.Throw an AuthenticationException if the authentication process fails。抛出一个 * 异常AuthenticationException表示认证失败。 * * * @param request from which to extract parameters and perform the authentication * @param response the response, which may be needed if the implementation has to do a * redirect as part of a multi-stage authentication process (such as OpenID). * * @return the authenticated user token, or null if authentication is incomplete. * * @throws AuthenticationException if authentication fails. */
    public abstract Authentication attemptAuthentication(HttpServletRequest request,
            HttpServletResponse response) throws AuthenticationException, IOException,
            ServletException;

    /** * Default behaviour for successful authentication.认证成功时的缺省行为。 * * 1. Sets the successful Authentication object on the SecurityContextHolder * 2. Informs the configured RememberMeServices of the successful login * 3.Fires an InteractiveAuthenticationSuccessEvent via the configured * ApplicationEventPublisher * 4.Delegates additional behaviour to the AuthenticationSuccessHandler. * * * Subclasses can override this method to continue the FilterChain after * successful authentication. * @param request * @param response * @param chain * @param authResult the object returned from the attemptAuthentication * method. * @throws IOException * @throws ServletException */
    protected void successfulAuthentication(HttpServletRequest request,
            HttpServletResponse response, FilterChain chain, Authentication authResult)
            throws IOException, ServletException {

        if (logger.isDebugEnabled()) {
            logger.debug("Authentication success. Updating SecurityContextHolder to contain: "
                    + authResult);
        }

        SecurityContextHolder.getContext().setAuthentication(authResult);

        rememberMeServices.loginSuccess(request, response, authResult);

        // Fire event
        if (this.eventPublisher != null) {
            eventPublisher.publishEvent(new InteractiveAuthenticationSuccessEvent(
                    authResult, this.getClass()));
        }

        successHandler.onAuthenticationSuccess(request, response, authResult);
    }

    /** * Default behaviour for unsuccessful authentication. * 认证失败时的缺省行为 * * 1.Clears the SecurityContextHolder * 2.Stores the exception in the session (if it exists or * allowSesssionCreation is set to true) * 3.Informs the configured RememberMeServices of the failed login * 4.Delegates additional behaviour to the AuthenticationFailureHandler. * */
    protected void unsuccessfulAuthentication(HttpServletRequest request,
            HttpServletResponse response, AuthenticationException failed)
            throws IOException, ServletException {
        SecurityContextHolder.clearContext();

        if (logger.isDebugEnabled()) {
            logger.debug("Authentication request failed: " + failed.toString(), failed);
            logger.debug("Updated SecurityContextHolder to contain null Authentication");
            logger.debug("Delegating to authentication failure handler " + failureHandler);
        }

        rememberMeServices.loginFail(request, response);

        failureHandler.onAuthenticationFailure(request, response, failed);
    }

    protected AuthenticationManager getAuthenticationManager() {
        return authenticationManager;
    }

    public void setAuthenticationManager(AuthenticationManager authenticationManager) {
        this.authenticationManager = authenticationManager;
    }

    /** * Sets the URL that determines if authentication is required * * @param filterProcessesUrl */
    public void setFilterProcessesUrl(String filterProcessesUrl) {
        setRequiresAuthenticationRequestMatcher(new AntPathRequestMatcher(
                filterProcessesUrl));
    }

    public final void setRequiresAuthenticationRequestMatcher(
            RequestMatcher requestMatcher) {
        Assert.notNull(requestMatcher, "requestMatcher cannot be null");
        this.requiresAuthenticationRequestMatcher = requestMatcher;
    }

    public RememberMeServices getRememberMeServices() {
        return rememberMeServices;
    }

    public void setRememberMeServices(RememberMeServices rememberMeServices) {
        Assert.notNull(rememberMeServices, "rememberMeServices cannot be null");
        this.rememberMeServices = rememberMeServices;
    }

    /** * Indicates if the filter chain should be continued prior to delegation to * #successfulAuthentication(HttpServletRequest, HttpServletResponse, FilterChain, Authentication) * , which may be useful in certain environment (such as Tapestry applications). * Defaults to false. */
    public void setContinueChainBeforeSuccessfulAuthentication(
            boolean continueChainBeforeSuccessfulAuthentication) {
        this.continueChainBeforeSuccessfulAuthentication = continueChainBeforeSuccessfulAuthentication;
    }

    public void setApplicationEventPublisher(ApplicationEventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }

    public void setAuthenticationDetailsSource(
            AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource) {
        Assert.notNull(authenticationDetailsSource,
                "AuthenticationDetailsSource required");
        this.authenticationDetailsSource = authenticationDetailsSource;
    }

    public void setMessageSource(MessageSource messageSource) {
        this.messages = new MessageSourceAccessor(messageSource);
    }

    protected boolean getAllowSessionCreation() {
        return allowSessionCreation;
    }

    public void setAllowSessionCreation(boolean allowSessionCreation) {
        this.allowSessionCreation = allowSessionCreation;
    }

    /** * The session handling strategy which will be invoked immediately after an * authentication request is successfully processed by the * AuthenticationManager. Used, for example, to handle changing of the * session identifier to prevent session fixation attacks. * * @param sessionStrategy the implementation to use. If not set a null implementation * is used. */
    public void setSessionAuthenticationStrategy(
            SessionAuthenticationStrategy sessionStrategy) {
        this.sessionStrategy = sessionStrategy;
    }

    /** * Sets the strategy used to handle a successful authentication. By default a * SavedRequestAwareAuthenticationSuccessHandler is used. */
    public void setAuthenticationSuccessHandler(
            AuthenticationSuccessHandler successHandler) {
        Assert.notNull(successHandler, "successHandler cannot be null");
        this.successHandler = successHandler;
    }

    public void setAuthenticationFailureHandler(
            AuthenticationFailureHandler failureHandler) {
        Assert.notNull(failureHandler, "failureHandler cannot be null");
        this.failureHandler = failureHandler;
    }

    protected AuthenticationSuccessHandler getSuccessHandler() {
        return successHandler;
    }

    protected AuthenticationFailureHandler getFailureHandler() {
        return failureHandler;
    }
}

参考文章

• Spring Security Web 5.1.2 源码解析 – 安全相关Filter清单
• SavedRequestAwareAuthenticationSuccessHandler
• SimpleUrlAuthenticationFailureHandler
• WebAuthenticationDetailsSource