【SpringSecurity新手村系列】（3）自定义登录页与表单认证定义登录页与表单认证本文围绕自定义登录页展开，详解

第三章自定义登录页与表单认证

本章将介绍如何自定义登录页面，配置登录成功/失败后的跳转逻辑，告别框架默认的登录页。

在上一篇文章中，我们实现了数据库认证，但登录页面仍然是框架自动生成的默认页面。在实际项目中，我们需要使用自己的登录页面，并配置个性化的跳转逻辑。本篇文章将详细介绍相关配置。

一、问题切入

第二章中我们使用的仍然是框架默认的登录页面：

样式千篇一律，无法满足项目 UI 设计需求
无法自定义登录成功后的跳转逻辑
无法在登录页添加验证码、社交登录等功能
无法获取登录失败的具体错误信息

我们需要一个可定制的登录解决方案。

二、解决方案：表单认证配置

在 SecurityConfig 中使用 .formLogin() 配置自定义登录页：

@Configuration
public class SecurityConfig {
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) {
        return http
                .formLogin(form -> form
                        .loginProcessingUrl("/login")  // 表单提交地址
                        .loginPage("/tologin")           // 登录页URL
                        .defaultSuccessUrl("/", true)   // 登录成功跳转
                )
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/tologin").permitAll()  // 无需认证
                        .anyRequest().authenticated()              // 其他需认证
                )
                .build();
    }
}

说明：你的 ss03 当前代码中是 loginProcessingUrl("/login")，而 ss04 已改为 "/user/login"。两者都可以，但必须和前端表单 action 保持一致。

三、原理阐释：SecurityFilterChain

3.1 安全过滤链

Spring Security 的核心是 SecurityFilterChain，它由多个 Filter 组成：

请求 → SecurityContextPersistenceFilter
     → HeaderWriterFilter
     →LogoutFilter
     → UsernamePasswordAuthenticationFilter ← 这里处理登录
     → DefaultLoginPageGeneratingFilter
     → DefaultLogoutPageGeneratingFilter
     → CsrfFilter
     → RequestCacheContextFilter
     → AuthorizationFilter ← 这里检查权限
     → ...

每个 Filter 只负责自己的职责，多个 Filter 按照顺序执行，形成责任链。

3.2 配置参数详解

配置项

说明

loginProcessingUrl

表单提交的目标URL，需与前端表单 action 一致

loginPage

自定义登录页URL，认证失败时自动重定向至此

defaultSuccessUrl

登录成功后强制跳转的URL

successForwardUrl

登录成功后转发到指定 URL

failureUrl

登录失败后跳转的 URL

permitAll()

指定路径无需认证即可访问

authenticated()

其他所有请求需要认证

3.3 Lambda 配置风格

本章采用 Spring Security 7.x 推荐的 Lambda 配置风格：

// 旧版风格
http
    .formLogin()
        .loginProcessingUrl("/login")
        .loginPage("/tologin")
        .and()
    .authorizeHttpRequests()
        .antMatchers("/tologin").permitAll()
        .anyRequest().authenticated();

// Lambda 风格（推荐）
http
    .formLogin(form -> form
        .loginProcessingUrl("/login")
        .loginPage("/tologin")
    )
    .authorizeHttpRequests(auth -> auth
        .requestMatchers("/tologin").permitAll()
        .anyRequest().authenticated()
    );

Lambda 风格更简洁、可读性更高，是 Spring Security 7.x 推荐的写法。

四、控制器实现

@Controller
public class UserController {
    // 访问根路径
    @ResponseBody
    @RequestMapping("/")
    public String index() {
        return "欢迎回来";
    }

    // 跳转登录页
    @RequestMapping("/tologin")
    public String toLogin() {
        return "login";  // 对应 src/main/resources/templates/login.html
    }
}

五、前端登录页

使用 Thymeleaf 模板引擎创建登录页面 login.html：

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>登录</title>
</head>
<body>
<form action="/login" method="post">
    用户名：<input type="text" name="username"> <br/>
    密码：<input type="password" name="password"> <br/>
    <!-- CSRF Token：防止跨站请求伪造 -->
    <input type="hidden" name="_csrf" th:value="${_csrf.token}">
    <input type="submit" value="登录">
</form>
</body>
</html>

关键点：

表单 action="/login" 必须与 SecurityConfig 中的 loginProcessingUrl 保持一致

必须包含 CSRF Token th:value="${_csrf.token}"，否则登录请求会被拒绝

5.1 深入理解这行隐藏域

<input type="hidden" name="_csrf" th:value="${_csrf.token}">

这行代码不是“可选增强”，而是开启 CSRF 防护时，POST 表单能通过校验的关键。

（1）它在做什么

name="_csrf"：告诉 Spring Security 这是 CSRF 参数（默认参数名就是 _csrf）
th:value="${_csrf.token}"：Thymeleaf 在服务端渲染页面时，把当前请求对应的 token 值写入这个隐藏域

用户提交表单时，这个隐藏字段会和 username/password 一起提交到后端。

（2）为什么需要它

CSRF（跨站请求伪造）的典型攻击方式是：

用户已在你的站点登录（浏览器里有有效会话 Cookie）
用户访问了攻击者网站
攻击者网站偷偷向你的站点发起一个“状态变更请求”（比如转账、改密码、发帖）

因为浏览器会自动带上 Cookie，后端如果只认 Cookie，就可能误以为这是用户本人操作。

Spring Security 的做法是：除了 Cookie，再要求请求里必须带一个后端签发的随机 token。攻击者站点拿不到这个 token，所以伪造请求通常会失败。

（3）后端如何校验

在过滤器链里，CsrfFilter 会检查：

请求是否属于需要保护的方法（POST/PUT/PATCH/DELETE）
请求参数或请求头里是否携带 token
这个 token 是否与服务端保存的 token 匹配

不匹配就拒绝，请求通常返回 403。

（4）为什么 GET 一般不需要带

Spring Security 默认认为 GET/HEAD/OPTIONS/TRACE 是“只读”请求，不会修改服务端状态，所以不强制 CSRF token。会修改状态的请求（尤其 POST）才是重点防护对象。

（5）和前后端分离场景的区别

你这个 ss03 是服务端模板渲染（Thymeleaf），所以直接在表单放隐藏域是最自然的方式。

如果是前后端分离（SPA），通常会：

后端把 CSRF token 放在响应头或 Cookie
前端在后续 AJAX 请求头里回传（如 X-CSRF-TOKEN）

（6）如果你去掉这行会怎样

登录表单使用 POST 提交时，CsrfFilter 校验失败
常见现象：登录失败、403、或者一直跳转回登录页

所以这行隐藏域要和你的 POST 表单一起保留。

六、补充依赖

如需使用 Thymeleaf 模板引擎，需添加以下依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

七、核心概念总结

配置

说明

formLogin()

启用表单认证，替代 HTTP Basic 认证

loginProcessingUrl()

指定表单提交地址

loginPage()

指定自定义登录页

Lambda 配置风格

Spring Security 7.x 推荐写法

CSRF Token

防止跨站请求伪造

八、总结

本篇文章介绍了以下核心内容：

SecurityFilterChain：安全过滤器链，多个 Filter 按顺序执行
formLogin()：启用表单认证
loginProcessingUrl()：指定表单提交地址，需与前端一致
loginPage()：指定自定义登录页，支持任何视图技术
Lambda 配置风格：Spring Security 7.x 推荐写法
CSRF 防护：表单必须包含 CSRF Token

下一篇文章我们将介绍验证码功能的实现。

编辑者：Flittly
更新时间：2026年4月

【SpringSecurity新手村系列】（3）自定义登录页与表单认证

第三章 自定义登录页与表单认证