Spring Security 入门指南：构建安全可靠的 Java 应用

在现代 Web 应用开发中，安全性是不可或缺的一环。无论是用户认证（Authentication）还是资源授权（Authorization），都需要一套健壮的机制来保障应用和数据的安全。手动实现这些安全功能既耗时又容易出错。Spring Security 作为 Spring 生态系统中的一个强大安全框架，为 Java 应用提供了全面且灵活的安全解决方案。

本篇文章将带你从零开始认识 Spring Security，理解其核心概念，学习如何在 Spring Boot 应用中进行基本配置，并构建一个简单的安全示例。

第一部分：认识 Spring Security

1.1 什么是 Spring Security？

Spring Security 是一个功能强大且高度可定制的认证和访问控制框架。它是 Spring 框架的模块之一，旨在为基于 Spring 的企业级应用提供声明式的安全防护能力。通过 Spring Security，开发者可以将安全逻辑与业务逻辑分离，极大地提高了开发效率和代码的可维护性。

1.2 为什么选择 Spring Security？

功能全面： 它涵盖了认证、授权、会话管理、防止 CSRF 和 XSS 攻击等多种安全功能。
高度可定制： Spring Security 提供了丰富的扩展点，可以轻松集成各种认证机制（如数据库、LDAP、OAuth2、JWT 等）和授权策略。
与 Spring 生态无缝集成： 作为 Spring 家族的一员，它与 Spring MVC、Spring Boot 等其他 Spring 项目集成非常方便。
广泛的应用： 它是 Java 领域事实上的企业级应用安全标准。
降低开发成本： 提供了开箱即用的认证和授权实现，避免了重复造轮子。

1.3 核心功能概览

Spring Security 的核心功能可以概括为两大方面：

认证 (Authentication)： 验证用户身份的过程。确定“你是谁”。例如，用户输入用户名和密码登录。
授权 (Authorization)： 验证用户是否有权限访问某个资源或执行某个操作的过程。确定“你能做什么”。例如，只有管理员才能访问管理页面。

Spring Security 的设计围绕着一系列过滤器链（Filter Chain）进行，这些过滤器在请求到达你的 Controller 或 Service 之前拦截请求，执行安全检查。

第二部分：核心概念解析

理解 Spring Security 的核心概念是掌握它的关键。以下是一些最基本且重要的概念：

2.1 `Authentication` (认证对象)

Authentication 是 Spring Security 中代表当前用户身份的对象。它通常包含：

Principal： 用户的身份，可以是用户名、用户对象或任何能够唯一标识用户的信息。
Credentials： 用户的凭证，通常是密码。在认证成功后，出于安全考虑，凭证通常会被擦除。
Authorities： 用户拥有的权限列表，通常表示为 GrantedAuthority 对象集合，如角色（Role）或权限（Permission）。
Details： 与 Web 请求相关的额外信息，如用户的 IP 地址、Session ID 等。

2.2 `GrantedAuthority` (授权)

GrantedAuthority 代表用户拥有的权限。最常见的 GrantedAuthority 实现是表示角色的字符串，例如 "ROLE_ADMIN" 或 "ROLE_USER"。Spring Security 的授权决策通常基于这些 GrantedAuthority。

2.3 `SecurityContext` (安全上下文)

SecurityContext 存储了当前应用程序中正在与应用程序交互的用户的 Authentication 对象。它是 Spring Security 中持有当前用户身份信息的地方。

2.4 `SecurityContextHolder` (安全上下文持有者)

SecurityContextHolder 是一个静态类，用于访问 SecurityContext。默认情况下，它使用 ThreadLocal 策略，这意味着 SecurityContext 是与当前线程绑定的。这样，在同一个请求处理线程中的任何地方（Service 层、DAO 层等），都可以通过 SecurityContextHolder 轻松获取当前用户的身份和权限信息。

java Authentication authentication = SecurityContextHolder.getContext().getAuthentication(); String currentUserName = authentication.getName(); // 获取当前用户的权限列表 Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities();

2.5 `UserDetailsService` (用户详情服务)

UserDetailsService 是一个接口，用于加载用户特定的数据。它有一个核心方法 loadUserByUsername(String username)，根据用户名查找并返回一个 UserDetails 对象。

2.6 `UserDetails` (用户详情)

UserDetails 是一个接口，代表用户的核心信息，包括：

用户名 (getUsername())
密码 (getPassword())
用户是否启用 (isEnabled())
用户账户是否未过期 (isAccountNonExpired())
用户凭证是否未过期 (isCredentialsNonExpired())
用户账户是否未锁定 (isAccountNonLocked())
用户拥有的权限 (getAuthorities())

UserDetails 提供了认证所需的全部信息。UserDetailsService 加载 UserDetails 后，Spring Security 会使用这些信息来验证用户提供的凭证。

2.7 `PasswordEncoder` (密码编码器)

出于安全原因，绝不应该明文存储用户密码。PasswordEncoder 接口定义了密码的加密和匹配逻辑。Spring Security 推荐使用 BCrypt、SCrypt、Argon2 等强哈希算法。BCryptPasswordEncoder 是一个常用的选择。

2.8 `AuthenticationManager` (认证管理器)

AuthenticationManager 是执行认证的核心接口。它接收一个 Authentication 请求对象，并返回一个完全填充（已认证）的 Authentication 对象，或者抛出 AuthenticationException。

2.9 `AuthenticationProvider` (认证提供者)

AuthenticationManager 可以委托给一个或多个 AuthenticationProvider 来实际执行认证逻辑。不同的 AuthenticationProvider 可以支持不同的认证方式，例如：

DaoAuthenticationProvider：使用 UserDetailsService 和 PasswordEncoder 进行基于用户名/密码的认证。
LdapAuthenticationProvider：进行 LDAP 认证。
等等。

AuthenticationManager 会尝试使用其配置的 AuthenticationProvider 列表来处理认证请求，直到找到一个能够处理该请求的 AuthenticationProvider 并成功完成认证。

2.10 `SecurityFilterChain` (安全过滤链)

这是 Spring Security 在 Web 应用中的核心处理机制。当一个 HTTP 请求到达应用时，它会首先通过一个 DelegatingFilterProxy，这个代理会将请求转发给一个 FilterChainProxy。FilterChainProxy 内部包含了一个或多个 SecurityFilterChain。每个 SecurityFilterChain 包含了一系列有序的 Filter，例如用于处理认证、授权、Session 管理、CSRF 保护等的 Filter。请求会依次通过这个链中的 Filter，直到某个 Filter 处理了请求并生成响应（如重定向到登录页），或者请求通过了所有 Filter 并继续流向你的 Controller。

在现代 Spring Boot 应用中，我们通常通过配置一个或多个 @Bean 类型的 SecurityFilterChain 来定义安全规则。

第三部分：Spring Boot 项目中的基本配置

Spring Boot 为 Spring Security 提供了强大的自动配置能力，这使得入门变得非常简单。

3.1 添加依赖

首先，在你的 Spring Boot 项目的 pom.xml (Maven) 或 build.gradle (Gradle) 文件中添加 Spring Security 的 starter 依赖：

Maven:

“`xml

org.springframework.boot
spring-boot-starter-security

org.springframework.boot
spring-boot-starter-web

org.thymeleaf.extras
thymeleaf-extras-springsecurity6

“`

Gradle:

gradle implementation 'org.springframework.boot:spring-boot-starter-security' implementation 'org.springframework.boot:spring-boot-starter-web' // 可选：如果需要Thymeleaf集成安全标签 implementation 'org.thymeleaf.extras:thymeleaf-extras-springsecurity6'

添加依赖后，Spring Boot 会自动配置 Spring Security。默认情况下：

所有请求都需要认证。
应用启动时会在控制台打印一个随机生成的密码。
提供一个默认的登录页面 /login 和退出页面 /logout。
支持基本的表单登录。

你可以尝试运行应用并访问任何页面，都会被重定向到默认的登录页。使用用户名 user 和启动时控制台打印的密码即可登录。

3.2 自定义安全配置

虽然默认配置很方便，但在实际应用中我们通常需要自定义安全规则、用户存储方式和密码编码器。这通常通过创建一个配置类来实现。

在现代 Spring Security 配置中（推荐 Spring Security 6+ 和 Spring Boot 3+），我们不再使用 WebSecurityConfigurerAdapter（它已被弃用）。取而代之的是，我们定义一个或多个 @Bean 类型的 SecurityFilterChain 来配置 HTTP 安全规则，并定义 @Bean 类型的 UserDetailsService 和 PasswordEncoder。

创建一个配置类，例如 SecurityConfig.java：

“`java
package com.example.securitydemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity // 启用Spring Security的Web安全功能
public class SecurityConfig {

// 1. 配置 SecurityFilterChain：定义HTTP请求的安全规则
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http
        // 配置请求授权
        .authorizeHttpRequests(authorizeRequests ->
            authorizeRequests
                // 允许访问 /public/** 路径下的所有资源，不需要认证
                .requestMatchers("/public/**").permitAll()
                // 允许访问 / 根路径，不需要认证
                .requestMatchers("/").permitAll()
                // 只有拥有 ADMIN 角色的用户才能访问 /admin/** 路径
                .requestMatchers("/admin/**").hasRole("ADMIN")
                // 所有其他请求都需要认证
                .anyRequest().authenticated()
        )
        // 配置表单登录
        .formLogin(formLogin ->
            formLogin
                // 指定自定义登录页面的URL (可选，默认是/login)
                // .loginPage("/login")
                // 处理登录请求的URL (默认是/login POST)
                // .loginProcessingUrl("/doLogin")
                // 登录成功后重定向的URL (默认是/, 也可以指定)
                .defaultSuccessUrl("/welcome", true)
                // 登录失败后重定向的URL (默认是/login?error)
                // .failureUrl("/login?error")
                // 允许所有用户访问登录页面 (如果使用了自定义登录页)
                .permitAll()
        )
        // 配置退出登录
        .logout(logout ->
            logout
                // 退出登录的处理URL (默认是/logout POST)
                // .logoutUrl("/logout")
                // 退出登录成功后重定向的URL
                .logoutSuccessUrl("/?logout") // 退出成功后重定向到根路径并带一个参数
                // 使当前Session失效
                .invalidateHttpSession(true)
                // 清除认证信息
                .deleteCookies("JSESSIONID") // 可选：清除Session cookie
                .permitAll() // 允许所有用户访问退出登录URL
        );
        // 其他配置，如CSRF保护，会话管理等，默认是开启的，后续可以按需配置

    return http.build();
}

// 2. 配置 UserDetailsService：定义如何查找用户详情
// 这里使用内存存储的方式，实际应用中通常会从数据库加载
@Bean
public UserDetailsService userDetailsService(PasswordEncoder passwordEncoder) {
    // 创建一个普通用户
    UserDetails user = User.builder()
        .username("user")
        // 注意：密码需要使用 PasswordEncoder 编码
        .password(passwordEncoder.encode("password"))
        .roles("USER") // 设置角色
        .build();

    // 创建一个管理员用户
    UserDetails admin = User.builder()
        .username("admin")
        .password(passwordEncoder.encode("adminpass"))
        .roles("ADMIN", "USER") // 设置多个角色
        .build();

    // 将用户添加到内存管理器中
    return new InMemoryUserDetailsManager(user, admin);
}

// 3. 配置 PasswordEncoder：定义密码的编码方式
@Bean
public PasswordEncoder passwordEncoder() {
    // 推荐使用 BCryptPasswordEncoder
    return new BCryptPasswordEncoder();
}

// 注意：在 Spring Boot 2.x 及之前版本，可能需要通过重写 configure 方法来配置
// 但在 Spring Boot 3+ (Spring Security 6+) 中，推荐使用 Bean 的方式

}
“`

3.3 理解配置的含义

@Configuration：标记这是一个配置类。
@EnableWebSecurity：启用 Spring Security 的 Web 安全支持，会加载必要的 Spring Security Bean。
securityFilterChain Bean：
- 使用 HttpSecurity 对象进行配置，这是定义 HTTP 请求安全规则的核心。
- authorizeHttpRequests(): 开始配置请求授权规则。
- requestMatchers("/public/**").permitAll(): 允许访问 /public/ 路径下的所有子路径，不需要认证。
- requestMatchers("/").permitAll(): 允许访问根路径 /，不需要认证。
- requestMatchers("/admin/**").hasRole("ADMIN"): 只有拥有 ADMIN 角色的用户才能访问 /admin/ 路径下的资源。注意，使用 hasRole() 时，Spring Security 会自动给传入的角色名加上 ROLE_ 前缀进行匹配，所以如果你的用户存储中角色是 ROLE_ADMIN，这里写 hasRole("ADMIN") 即可。如果你的权限不是以 ROLE_ 开头，应该使用 hasAuthority("...")。
- anyRequest().authenticated(): 所有其他未匹配到的请求都需要认证。
- formLogin(): 启用默认的表单登录功能。你可以通过链式调用配置登录页、登录处理URL、成功/失败重定向等。permitAll() 是允许所有人访问登录相关的页面和URL，这很重要，否则用户连登录页都看不到。
- logout(): 启用默认的退出登录功能。同样可以配置退出URL、成功重定向等。permitAll() 是允许所有人访问退出登录相关的URL。
userDetailsService Bean：
- 这里创建了一个 InMemoryUserDetailsManager，它将用户详情存储在内存中。这适用于简单的示例或测试。
- User.builder() 是创建 UserDetails 对象的一个便捷方式。
- passwordEncoder.encode("...") 表明密码必须经过编码才能存储。
- roles("...") 设置用户的角色。
- 在实际应用中，你会注入一个持久层服务（如 JPA Repository）来从数据库加载用户数据，然后返回自定义实现的 UserDetails 对象（或者使用 Spring Security 提供的 User 类）。
passwordEncoder Bean：
- 定义使用的密码编码器。BCryptPasswordEncoder 是一个安全的、推荐的选择。它是一个实现了 PasswordEncoder 接口的 Bean，Spring Security 会自动使用它来验证登录时输入的密码与存储的编码密码是否匹配。

3.4 创建 Controller 示例

为了测试上述配置，创建几个简单的 Controller 方法：

“`java
package com.example.securitydemo.controller;

import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HomeController {

@GetMapping("/")
public String home() {
    return "Welcome! This is a public home page.";
}

@GetMapping("/public/hello")
public String publicHello() {
    return "This is a public endpoint: Hello!";
}

@GetMapping("/welcome")
public String welcome() {
    // 从 SecurityContextHolder 获取当前认证的用户信息
    Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
    String currentUserName = authentication.getName();
    return "Welcome, " + currentUserName + "! This is a welcome page after successful login.";
}

@GetMapping("/private/data")
public String privateData() {
    // 这个页面需要认证用户才能访问 (因为anyRequest().authenticated()规则)
    return "This is private data, only authenticated users can see this.";
}

@GetMapping("/admin/dashboard")
public String adminDashboard() {
    // 这个页面需要ADMIN角色才能访问
    return "Welcome Admin! This is the admin dashboard.";
}

}
“`

3.5 运行与测试

运行你的 Spring Boot 应用。

访问 / 或 /public/hello: 应该直接显示对应的欢迎信息，不需要登录。
访问 /private/data: 应该被重定向到 /login 页面（默认的 Spring Security 登录页）。
- 使用用户名 user 和密码 password 登录。成功后，应该被重定向到 /welcome 页面，并显示 “Welcome, user!…”。再次访问 /private/data 应该能看到私有数据。
- 使用用户名 admin 和密码 adminpass 登录。成功后，应该也被重定向到 /welcome 页面，并显示 “Welcome, admin!…”。再次访问 /private/data 也能看到私有数据。
访问 /admin/dashboard:
- 如果使用 user 登录，访问此页面应该会返回一个 403 Forbidden 错误，因为 user 没有 ADMIN 角色。
- 如果使用 admin 登录，访问此页面应该能看到管理员仪表盘的信息。
访问 /logout: 应该触发退出登录流程，并重定向到 / 页面。退出后再次尝试访问 /private/data 或 /admin/dashboard，会再次被重定向到登录页。

第四部分：深入与扩展

入门配置只是 Spring Security 功能的冰山一角。掌握了基本概念和配置后，你可以进一步学习和探索：

自定义登录页面： 通过 .loginPage("/your-login-page") 配置，并创建对应的 Controller 和 HTML 页面。
从数据库加载用户： 实现自己的 UserDetailsService，从数据库查询用户详情和权限。
集成其他认证方式： LDAP、OAuth2、JWT、SAML 等。
方法级别的安全： 使用 @PreAuthorize, @PostAuthorize, @Secured 注解在方法执行前或后进行授权检查。
CSRF (跨站请求伪造) 防护： Spring Security 默认开启，理解其原理和如何在表单中添加 CSRF token。
Session 管理： 控制并发会话、会话超时等。
Remember-Me 功能： 实现“记住我”功能，使用户在关闭浏览器后一段时间内无需重新登录。
自定义过滤器： 实现更复杂的安全逻辑。
权限表达式 (Security Expressions)： 如 hasRole('ADMIN'), hasAuthority('READ'), isAuthenticated(), principal.username == 'admin' 等，在配置授权规则时非常灵活。

第五部分：总结

Spring Security 是一个强大且灵活的框架，虽然初看起来可能有些复杂，但一旦理解了其核心概念（Authentication, Authorization, UserDetails, UserDetailsService, PasswordEncoder, SecurityFilterChain 等），并掌握了基本的配置方式，你就能轻松地为你的 Java 应用构建健壮的安全防线。

本指南带你迈出了 Spring Security 的第一步，通过简单的 Spring Boot 示例，展示了如何配置认证和基于 URL 的授权。继续深入学习官方文档和示例，实践不同的认证和授权场景，你将能够充分发挥 Spring Security 的潜力，为你的应用提供企业级的安全保障。

记住，安全是一个持续的过程，不仅依赖于框架本身，还需要开发者在设计和实现中时刻保持安全意识。

希望这篇入门指南对你有所帮助！

Spring Security 入门指南 – wiki基地

Spring Security 入门指南：构建安全可靠的 Java 应用

第一部分：认识 Spring Security

1.1 什么是 Spring Security？

1.2 为什么选择 Spring Security？

1.3 核心功能概览

第二部分：核心概念解析

2.1 `Authentication` (认证对象)

2.2 `GrantedAuthority` (授权)

2.3 `SecurityContext` (安全上下文)

2.4 `SecurityContextHolder` (安全上下文持有者)

2.5 `UserDetailsService` (用户详情服务)

2.6 `UserDetails` (用户详情)

2.7 `PasswordEncoder` (密码编码器)

2.8 `AuthenticationManager` (认证管理器)

2.9 `AuthenticationProvider` (认证提供者)

2.10 `SecurityFilterChain` (安全过滤链)

第三部分：Spring Boot 项目中的基本配置

3.1 添加依赖

3.2 自定义安全配置

3.3 理解配置的含义

3.4 创建 Controller 示例

3.5 运行与测试

第四部分：深入与扩展

第五部分：总结

发表评论取消回复

Spring Security 入门指南：构建安全可靠的 Java 应用

第一部分：认识 Spring Security

1.1 什么是 Spring Security？

1.2 为什么选择 Spring Security？

1.3 核心功能概览

第二部分：核心概念解析

2.1 Authentication (认证对象)

2.2 GrantedAuthority (授权)

2.3 SecurityContext (安全上下文)

2.4 SecurityContextHolder (安全上下文持有者)

2.5 UserDetailsService (用户详情服务)

2.6 UserDetails (用户详情)

2.7 PasswordEncoder (密码编码器)

2.8 AuthenticationManager (认证管理器)

2.9 AuthenticationProvider (认证提供者)

2.10 SecurityFilterChain (安全过滤链)

第三部分：Spring Boot 项目中的基本配置

3.1 添加依赖

3.2 自定义安全配置

3.3 理解配置的含义

3.4 创建 Controller 示例

3.5 运行与测试

第四部分：深入与扩展

第五部分：总结

发表评论 取消回复

2.1 `Authentication` (认证对象)

2.2 `GrantedAuthority` (授权)

2.3 `SecurityContext` (安全上下文)

2.4 `SecurityContextHolder` (安全上下文持有者)

2.5 `UserDetailsService` (用户详情服务)

2.6 `UserDetails` (用户详情)

2.7 `PasswordEncoder` (密码编码器)

2.8 `AuthenticationManager` (认证管理器)

2.9 `AuthenticationProvider` (认证提供者)

2.10 `SecurityFilterChain` (安全过滤链)

发表评论取消回复