SpringSecurity实战教程（十七）企业级安全方案设计 - 多因素认证（MFA）实现

1
@Service
2
public class UserServiceImpl implements IUserService {
3

4
    @Autowired
5
    private UserMapper userMapper;
6

7
    private final BCryptPasswordEncoder passwordEncoder = new BCryptPasswordEncoder();
8

9
    @Override
10
    public User findByUsername(String username) {
11
        return userMapper.selectOne(new QueryWrapper<User>().eq("username", username));
12
    }
13

14
    @Override
15
    public void register(User user) {
16
        // 加密密码
17
        user.setPassword(passwordEncoder.encode(user.getPassword()));
18
        user.setEnabled(true);
19
        user.setMfaEnabled(false);
20
        user.setMfaSecret(null);
21
        userMapper.insert(user);
22
    }
23

24
    @Override
25
    public void enableMfa(Long userId) {
26
        // 为用户生成 TOTP Secret 并更新
27
        User u = userMapper.selectById(userId);
28
        String secret = TotpUtils.generateSecretKey();
29
        u.setMfaSecret(secret);
30
        u.setMfaEnabled(true);
31
        userMapper.updateById(u);
32
    }
33

34
    @Override
35
    public boolean verifyTotp(Long userId, int code) {
36
        User u = userMapper.selectById(userId);
37
        if (u == null || !u.getMfaEnabled() || u.getMfaSecret() == null) {
38
            return false;
39
        }
40
        return TotpUtils.verifyTotp(u.getMfaSecret(), code);
41
    }
42
}

1
/**
2
 * 第一步：校验用户名 + 密码
3
 * 如果用户启用 MFA，则抛出 MfaRequiredException，后续由 MfaAuthenticationFilter 处理
4
 */
5
@Component
6
public class CustomAuthenticationProvider implements AuthenticationProvider {
7

8
    @Autowired
9
    private IUserService userService;
10

11
    private final BCryptPasswordEncoder passwordEncoder = new BCryptPasswordEncoder();
12

13
    @Override
14
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
15
        String username = authentication.getName();
16
        String password = (String) authentication.getCredentials();
17
        User user = userService.findByUsername(username);
18

19
        if (user == null || !user.getEnabled()) {
20
            throw new BadCredentialsException("用户名或密码错误");
21
        }
22
        if (!passwordEncoder.matches(password, user.getPassword())) {
23
            throw new BadCredentialsException("用户名或密码错误");
24
        }
25

26
        // 如果用户启用了 MFA，则抛出自定义异常，提示进行第二步验证
27
        if (Boolean.TRUE.equals(user.getMfaEnabled())) {
28
            throw new MfaRequiredException("MFA 验证必需", username);
29
        }
30

31
        // 未启用 MFA 则直接构建 Authentication
32
        return new UsernamePasswordAuthenticationToken(
33
                username, null,
34
                Collections.singletonList(new SimpleGrantedAuthority("ROLE_USER"))
35
        );
36
    }
37

38
    @Override
39
    public boolean supports(Class<?> authentication) {
40
        return UsernamePasswordAuthenticationToken.class.isAssignableFrom(authentication);
41
    }
42
}

1
/**
2
 * 该过滤器负责处理 /mfa-verify POST 请求，
3
 * 从 session 中获取待验证用户名，校验用户提交的 TOTP 码。
4
 */
5
@Component
6
public class MfaAuthenticationFilter extends AbstractAuthenticationProcessingFilter {
7

8
    private final IUserService userService;
9

10
    public MfaAuthenticationFilter(IUserService userService) {
11
        super(new AntPathRequestMatcher("/mfa-verify", "POST"));
12
        this.userService = userService;
13
        // 不让 Spring Security 为我们阻止 CSRF，示例中 CSRF 已关闭
14
    }
15

16
    @Override
17
    public Authentication attemptAuthentication(
18
            HttpServletRequest request,
19
            HttpServletResponse response
20
    ) throws IOException, ServletException {
21
        // 应用前端将用户名暂存到 sessionAttribute： "MFA_USER"
22
        String username = (String) request.getSession().getAttribute("MFA_USER");
23
        if (username == null) {
24
            throw new RuntimeException("会话中找不到待 MFA 用户");
25
        }
26

27
        // 获取用户提交的 TOTP 码
28
        String codeStr = request.getParameter("code");
29
        if (codeStr == null || codeStr.isEmpty()) {
30
            throw new RuntimeException("TOTP 码不能为空");
31
        }
32

33
        int code;
34
        try {
35
            code = Integer.parseInt(codeStr);
36
        } catch (NumberFormatException e) {
37
            throw new RuntimeException("TOTP 码格式不正确");
38
        }
39

40
        // 从数据库校验 TOTP
41
        User user = userService.findByUsername(username);
42
        boolean valid = userService.verifyTotp(user.getId(), code);
43
        if (!valid) {
44
            throw new RuntimeException("TOTP 验证失败");
45
        }
46

47
        // 验证成功，构建真正的 Authentication 对象
48
        UsernamePasswordAuthenticationToken auth =
49
                new UsernamePasswordAuthenticationToken(
50
                        username, null, Collections.singletonList(() -> "ROLE_USER")
51
                );
52
        return auth;
53
    }
54

55
    @Override
56
    protected void successfulAuthentication(
57
            HttpServletRequest request,
58
            HttpServletResponse response,
59
            FilterChain chain,
60
            Authentication authResult
61
    ) throws IOException, ServletException {
62
        // 将最终的 Authentication 填入 SecurityContext
63
        SecurityContextHolder.getContext().setAuthentication(authResult);
64
        // 登录成功后清除 session 中的 MFA 用户标志
65
        request.getSession().removeAttribute("MFA_USER");
66
        // 跳转到首页
67
        response.sendRedirect("/");
68
    }
69

70
    @Override
71
    protected void unsuccessfulAuthentication(
72
            HttpServletRequest request,
73
            HttpServletResponse response,
74
            AuthenticationException failed
75
    ) throws IOException, ServletException {
76
        // 验证失败，跳回 MFA 验证页面
77
        response.setContentType(MediaType.TEXT_PLAIN_VALUE);
78
        response.getWriter().write("MFA 验证失败：" + failed.getMessage());
79
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
80
    }
81
}

1
/**
2
 * 处理第一步用户名/密码登录失败或触发 MFA 的情况
3
 */
4
@Component
5
public class CustomAuthenticationFailureHandler implements AuthenticationFailureHandler {
6

7
    @Override
8
    public void onAuthenticationFailure(
9
            HttpServletRequest request,
10
            HttpServletResponse response,
11
            AuthenticationException exception
12
    ) throws IOException, ServletException {
13
        // 如果是 MfaRequiredException，重定向到 /mfa 页面，并将用户名存入 session
14
        if (exception instanceof MfaRequiredException) {
15
            String username = ((MfaRequiredException) exception).getUsername();
16
            request.getSession().setAttribute("MFA_USER", username);
17
            // 重定向到 MFA 验证页面
18
            response.sendRedirect("/mfa");
19
        } else {
20
            // 普通登录失败，重定向回 /login?error
21
            response.sendRedirect("/login?error=true");
22
        }
23
    }
24
}

1
/**
2
 * 核心安全配置：
3
 *  1. 注入自定义 AuthenticationProvider
4
 *  2. 配置表单登录和 MfaAuthenticationFilter
5
 */
6
@Configuration
7
public class SecurityConfig {
8

9
    @Autowired
10
    private CustomAuthenticationProvider customAuthenticationProvider;
11

12
    @Autowired
13
    private MfaAuthenticationFilter mfaAuthenticationFilter;
14

15
    @Autowired
16
    private CustomAuthenticationFailureHandler customFailureHandler;
17

18
    @Bean
19
    public SecurityFilterChain filterChain(HttpSecurity http, AuthenticationConfiguration authConfig) throws Exception {
20
        // 禁用 CSRF 简化示例
21
        http.csrf(csrf -> csrf.disable());
22

23
        // 使用自定义 AuthenticationProvider 替换默认的 DaoAuthenticationProvider
24
        http.authenticationProvider(customAuthenticationProvider);
25

26
        // 1. 首先，配置表单登录
27
        http.authorizeHttpRequests(auth -> auth
28
                .requestMatchers("/login", "/register", "/css/**", "/js/**").permitAll()
29
                .anyRequest().authenticated()
30
        )
31
        .formLogin(form -> form
32
                .loginPage("/login")
33
                .loginProcessingUrl("/login") // 与表单提交 action 保持一致
34
                .failureHandler(customFailureHandler)
35
                .defaultSuccessUrl("/", true)
36
        );
37

38
        // 2. 注册 MFA 过滤器，它要在 UsernamePasswordAuthenticationFilter 之后执行
39
        http.addFilterAfter(mfaAuthenticationFilter, org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter.class);
40

41
        // 3. Session 管理：MFA 过程中会话保持
42
        http.sessionManagement(session -> session
43
                .sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED)
44
        );
45

46
        // 4. 未授权时返回 401
47
        http.exceptionHandling(ex -> ex.authenticationEntryPoint((request, response, authException) ->
48
                response.sendError(HttpServletResponse.SC_UNAUTHORIZED, "Unauthorized"))
49
        );
50

51
        return http.build();
52
    }
53

54
    // 若需手动获取 AuthenticationManager，可使用以下 Bean
55
    @Bean
56
    public AuthenticationManager authenticationManager(AuthenticationConfiguration authConfig) throws Exception {
57
        return authConfig.getAuthenticationManager();
58
    }
59
}

1
<!DOCTYPE html>
2
<html xmlns:th="http://www.thymeleaf.org">
3
<head>
4
    <title>登录</title>
5
</head>
6
<body>
7
<h2>登录</h2>
8
<form th:action="@{/login}" method="post">
9
    <div>
10
        <label>用户名:</label>
11
        <input type="text" name="username" required/>
12
    </div>
13
    <div>
14
        <label>密码:</label>
15
        <input type="password" name="password" required/>
16
    </div>
17
    <div th:if="${error}">
18
        <p style="color:red;">用户名或密码错误</p>
19
    </div>
20
    <div>
21
        <button type="submit">登录</button>
22
    </div>
23
</form>
24
<p>没有账号？<a th:href="@{/register}">注册</a></p>
25
</body>
26
</html>

1
<!DOCTYPE html>
2
<html xmlns:th="http://www.thymeleaf.org">
3
<head>
4
    <title>注册</title>
5
</head>
6
<body>
7
<h2>注册</h2>
8
<form th:action="@{/register}" method="post">
9
    <div>
10
        <label>用户名:</label>
11
        <input type="text" name="username" required/>
12
    </div>
13
    <div>
14
        <label>密码:</label>
15
        <input type="password" name="password" required/>
16
    </div>
17
    <div>
18
        <button type="submit">注册</button>
19
    </div>
20
</form>
21
<p>已有账号？<a th:href="@{/login}">登录</a></p>
22
</body>
23
</html>

1
<!DOCTYPE html>
2
<html xmlns:th="http://www.thymeleaf.org">
3
<head>
4
    <title>MFA 验证</title>
5
</head>
6
<body>
7
<h2>多因素认证</h2>
8
<p>用户 <span th:text="${username}"></span>，请输入手机应用上的 6 位动态验证码：</p>
9
<form th:action="@{/mfa-verify}" method="post">
10
    <div>
11
        <label>动态验证码:</label>
12
        <input type="text" name="code" pattern="\\d{6}" maxlength="6" required/>
13
    </div>
14
    <div>
15
        <button type="submit">验证</button>
16
    </div>
17
</form>
18
</body>
19
</html>

1
<!DOCTYPE html>
2
<html xmlns:th="http://www.thymeleaf.org">
3
<head>
4
    <title>启用 MFA</title>
5
</head>
6
<body>
7
<h2>启用多因素认证 (MFA)</h2>
8
<p>请使用 Google Authenticator 或其他兼容 TOTP 的应用扫描下方二维码，或使用秘钥手动添加：</p>
9
<div>
10
    <!-- 可以使用前端库生成二维码，此处直接展示 URI，方便生成 QR -->
11
    <p>OTPAuth URL: <span th:text="${otpAuthURL}"></span></p>
12
    <p>Secret Key: <span th:text="${secret}"></span></p>
13
</div>
14
<p>设置完成后，请退出重新登录并输入动态验证码。</p>
15
</body>
16
</html>