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


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


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


----

## 一、问题切入


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


- 样式千篇一律，无法满足项目 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/>
    
    <input type="hidden" name="_csrf" th:value="${_csrf.token}">
    <input type="submit" value="登录">
</form>
</body>
</html>
```
>关键点：
1. 表单 `action="/login"` 必须与 SecurityConfig 中的 `loginProcessingUrl` 保持一致
2. 必须包含 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（跨站请求伪造）的典型攻击方式是：


1. 用户已在你的站点登录（浏览器里有有效会话 Cookie）

2. 用户访问了攻击者网站

3. 攻击者网站偷偷向你的站点发起一个“状态变更请求”（比如转账、改密码、发帖）


因为浏览器会自动带上 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|防止跨站请求伪造|


----

## 八、总结


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


1. **SecurityFilterChain**：安全过滤器链，多个 Filter 按顺序执行

2. **formLogin()**：启用表单认证

3. **loginProcessingUrl()**：指定表单提交地址，需与前端一致

4. **loginPage()**：指定自定义登录页，支持任何视图技术

5. **Lambda 配置风格**：Spring Security 7.x 推荐写法

6. **CSRF 防护**：表单必须包含 CSRF Token


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


----

**编辑者**：Flittly

**更新时间**：2026年4月

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

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

自定义登录页与表单认证本文围绕自定义登录页展开，详解 formLogin、loginProcessingUrl 与跳转配置，重点解释 CSRF 隐藏域的作用、校验原理及常见错误，帮助你稳定完成表单登录改造。

后端

安全

学习Spring Security自定义登录页配置，掌握表单认证、CSRF防护和Lambda配置风格。实现个性化登录界面，配置登录成功/失败跳转逻辑，提升项目安全性。

验证码

数据库

2026采购季 | AI焕新·智启新局

captcha

tencentdb-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

【SpringSecurity新手村系列】（3）自定义登录页与表单认证-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐