Spring Security Web 5.1.2 源码解析 -- BasicAuthenticationFilter
概述
处理HTTP请求中的BASIC authorization头部，把认证结果写入SecurityContextHolder。
当一个HTTP请求中包含一个名字为Authorization的头部，并且其值格式是Basic xxx时，该Filter会认为这是一个BASIC authorization头部，其中xxx部分应该是一个base64编码的{username}:{password}字符串。比如用户名/密码分别为 admin/secret, 则对应的该头部是 : Basic YWRtaW46c2VjcmV0 。
该过滤器会从 HTTP BASIC authorization头部解析出相应的用户名和密码然后调用AuthenticationManager进行认证，成功的话会把认证了的结果写入到SecurityContextHolder中SecurityContext的属性authentication上面。同时还会做其他一些处理，比如Remember Me相关处理等等。
如果头部分析失败，该过滤器会抛出异常BadCredentialsException。
如果认证失败，则会清除SecurityContextHolder中的SecurityContext。并且不再继续filter chain的执行。
源代码解析
package org.springframework.security.web.authentication.www;
import java.io.IOException;
import java.util.Base64;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.springframework.security.authentication.AnonymousAuthenticationToken;
import org.springframework.security.authentication.AuthenticationDetailsSource;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.AuthenticationException;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.AuthenticationEntryPoint;
import org.springframework.security.web.authentication.NullRememberMeServices;
import org.springframework.security.web.authentication.RememberMeServices;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.util.Assert;
import org.springframework.web.filter.OncePerRequestFilter;
public class BasicAuthenticationFilter extends OncePerRequestFilter {
// ~ Instance fields
// ================================================================================================
// 创建Authentication对象时设置details属性所使用的详情来源
private AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource =
new WebAuthenticationDetailsSource();
private AuthenticationEntryPoint authenticationEntryPoint;
private AuthenticationManager authenticationManager;
private RememberMeServices rememberMeServices = new NullRememberMeServices();
private boolean ignoreFailure = false;
private String credentialsCharset = "UTF-8";
/**
* Creates an instance which will authenticate against the supplied
* AuthenticationManager and which will ignore failed authentication attempts,
* allowing the request to proceed down the filter chain.
*
* @param authenticationManager the bean to submit authentication requests to
*/
public BasicAuthenticationFilter(AuthenticationManager authenticationManager) {
Assert.notNull(authenticationManager, "authenticationManager cannot be null");
this.authenticationManager = authenticationManager;
this.ignoreFailure = true;
}
/**
* Creates an instance which will authenticate against the supplied
* AuthenticationManager and use the supplied AuthenticationEntryPoint
* to handle authentication failures.
*
* @param authenticationManager the bean to submit authentication requests to
* @param authenticationEntryPoint will be invoked when authentication fails.
* Typically an instance of BasicAuthenticationEntryPoint.
*/
public BasicAuthenticationFilter(AuthenticationManager authenticationManager,
AuthenticationEntryPoint authenticationEntryPoint) {
Assert.notNull(authenticationManager, "authenticationManager cannot be null");
Assert.notNull(authenticationEntryPoint,
"authenticationEntryPoint cannot be null");
this.authenticationManager = authenticationManager;
this.authenticationEntryPoint = authenticationEntryPoint;
}
// ~ Methods
// ========================================================================================================
@Override
public void afterPropertiesSet() {
Assert.notNull(this.authenticationManager,
"An AuthenticationManager is required");
if (!isIgnoreFailure()) {
Assert.notNull(this.authenticationEntryPoint,
"An AuthenticationEntryPoint is required");
}
}
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response, FilterChain chain)
throws IOException, ServletException {
final boolean debug = this.logger.isDebugEnabled();
// 获取请求头部 Authorization
String header = request.getHeader("Authorization");
if (header == null || !header.toLowerCase().startsWith("basic ")) {
// 如果头部 Authorization 未设置或者不是 basic 认证头部，则当前
// 请求不是该过滤器关注的对象，直接放行，继续filter chain 的执行
chain.doFilter(request, response);
return;
}
// 这是一个 http basic authentication 请求的情况，也就是说，已经检测到
// 请求头部 Authorization 的值符合格式(大小写不敏感) : "basic xxxxxx"
try {
// 分析头部 Authorization 获取用户名和密码
String[] tokens = extractAndDecodeHeader(header, request);
assert tokens.length == 2;
// 现在 tokens[0] 表示用户名， tokens[1] 表示密码
String username = tokens[0];
if (debug) {
this.logger
.debug("Basic Authentication Authorization header found for user '"
+ username + "'");
}
// 检测针对所请求的用户名 username 是否需要认证
if (authenticationIsRequired(username)) {
// 如果需要认证，使用所获取到的用户名/密码构建一个 UsernamePasswordAuthenticationToken,
// 然后执行认证流程
UsernamePasswordAuthenticationToken authRequest = new UsernamePasswordAuthenticationToken(
username, tokens[1]);
authRequest.setDetails(
this.authenticationDetailsSource.buildDetails(request));
// 执行认证
Authentication authResult = this.authenticationManager
.authenticate(authRequest);
if (debug) {
this.logger.debug("Authentication success: " + authResult);
}
// 认证成功，将完全认证的Authentication authRequest设置到 SecurityContextHolder
// 中的 SecurityContext 上。
SecurityContextHolder.getContext().setAuthentication(authResult);
// 认证成功时 RememberMe 相关处理
this.rememberMeServices.loginSuccess(request, response, authResult);
// 认证成功时的其他处理: 其实这个个空方法，什么都没做
onSuccessfulAuthentication(request, response, authResult);
}
}
catch (AuthenticationException failed) {
// 认证失败，清除 SecurityContextHolder 的安全上下文
SecurityContextHolder.clearContext();
if (debug) {
this.logger.debug("Authentication request for failed: " + failed);
}
// 认证失败 RememberMe 相关处理
this.rememberMeServices.loginFail(request, response);
// 认证失败时的其他处理: 其实这个个空方法，什么都没做
onUnsuccessfulAuthentication(request, response, failed);
if (this.ignoreFailure) {
chain.doFilter(request, response);
}
else {
this.authenticationEntryPoint.commence(request, response, failed);
}
return;
}
// 如果当前请求并非含有 http basic authentication 头部的请求，则直接放行，继续filter chain的执行
chain.doFilter(request, response);
}
/**
* Decodes the header into a username and password.
* 从指定的 http basic authentication 请求头部解码出一个用户名和密码
*
* @throws BadCredentialsException if the Basic header is not present or is not valid
* Base64
*/
private String[] extractAndDecodeHeader(String header, HttpServletRequest request)
throws IOException {
// 截取头部前6个字符之后的内容部分,使用字符集编码方式UTF-8
// 举例: 整个头部值为 "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
// 这里则是获取"QWxhZGRpbjpvcGVuIHNlc2FtZQ=="部分
byte[] base64Token = header.substring(6).getBytes("UTF-8");
// 使用 Base64 字符编码方式解码 base64Token
byte[] decoded;
try {
decoded = Base64.getDecoder().decode(base64Token);
}
catch (IllegalArgumentException e) {
throw new BadCredentialsException(
"Failed to decode basic authentication token");
}
// 使用指定的字符集credentialsCharset重新构建"{用户名}:{密码}"字符串
// credentialsCharset 缺省也是 UTF-8
String token = new String(decoded, getCredentialsCharset(request));
// 提取用户名,密码并返回之
int delim = token.indexOf(":");
if (delim == -1) {
throw new BadCredentialsException("Invalid basic authentication token");
}
return new String[] { token.substring(0, delim), token.substring(delim + 1) };
}
private boolean authenticationIsRequired(String username) {
// Only reauthenticate if username doesn't match SecurityContextHolder and user
// isn't authenticated
// (see SEC-53)
Authentication existingAuth = SecurityContextHolder.getContext()
.getAuthentication();
// 检测 SecurityContextHolder 中 SecurityContext 的 Authentication,
// 如果它为 null 或者尚未认证，则认为需要认证
if (existingAuth == null || !existingAuth.isAuthenticated()) {
return true;
}
// Limit username comparison to providers which use usernames (ie
// UsernamePasswordAuthenticationToken)
// (see SEC-348)
// 如果 SecurityContextHolder 中 SecurityContext 的 Authentication 是
// 已经认证状态，但是其中的用户名和这里的 username 不相同，也认为需要认证
if (existingAuth instanceof UsernamePasswordAuthenticationToken
&& !existingAuth.getName().equals(username)) {
return true;
}
// Handle unusual condition where an AnonymousAuthenticationToken is already
// present
// This shouldn't happen very often, as BasicProcessingFitler is meant to be
// earlier in the filter
// chain than AnonymousAuthenticationFilter. Nevertheless, presence of both an
// AnonymousAuthenticationToken
// together with a BASIC authentication request header should indicate
// reauthentication using the
// BASIC protocol is desirable. This behaviour is also consistent with that
// provided by form and digest,
// both of which force re-authentication if the respective header is detected (and
// in doing so replace
// any existing AnonymousAuthenticationToken). See SEC-610.
// 如果 SecurityContextHolder 中 SecurityContext 的 Authentication 是匿名认证，
// 则认为需要认证
if (existingAuth instanceof AnonymousAuthenticationToken) {
return true;
}
// 如果 SecurityContextHolder 中 SecurityContext 的 Authentication 是已认证状态,
// 并且是针对当前username的，则认为不需要认证
return false;
}
protected void onSuccessfulAuthentication(HttpServletRequest request,
HttpServletResponse response, Authentication authResult) throws IOException {
}
protected void onUnsuccessfulAuthentication(HttpServletRequest request,
HttpServletResponse response, AuthenticationException failed)
throws IOException {
}
protected AuthenticationEntryPoint getAuthenticationEntryPoint() {
return this.authenticationEntryPoint;
}
protected AuthenticationManager getAuthenticationManager() {
return this.authenticationManager;
}
protected boolean isIgnoreFailure() {
return this.ignoreFailure;
}
public void setAuthenticationDetailsSource(
AuthenticationDetailsSource<HttpServletRequest, ?> authenticationDetailsSource) {
Assert.notNull(authenticationDetailsSource,
"AuthenticationDetailsSource required");
this.authenticationDetailsSource = authenticationDetailsSource;
}
public void setRememberMeServices(RememberMeServices rememberMeServices) {
Assert.notNull(rememberMeServices, "rememberMeServices cannot be null");
this.rememberMeServices = rememberMeServices;
}
public void setCredentialsCharset(String credentialsCharset) {
Assert.hasText(credentialsCharset, "credentialsCharset cannot be null or empty");
this.credentialsCharset = credentialsCharset;
}
protected String getCredentialsCharset(HttpServletRequest httpRequest) {
return this.credentialsCharset;
}
}
参考文章
- Spring Security Web 5.1.2 源码解析 – 安全相关Filter清单