Spring Security 教程：从入门到精通（含 OAuth2 接入）

Spring Security 是 Spring 框架中备受推崇的安全模块，广泛应用于构建安全可靠的企业级应用程序。它提供了一套全面的解决方案，涵盖身份认证（Authentication）、授权（Authorization）以及防范各种网络安全威胁（如 CSRF、会话固定攻击等）。本文将带你深入探索 Spring Security，从基础概念到高级特性，最终实现 OAuth2 接入，助力你打造高度安全的 Web 应用。

一、环境准备

在开始学习之前，确保你的开发环境已经准备好以下工具：

• Java JDK：版本建议使用 JDK 8 或更高版本。可以通过命令 java -version 来检查已安装的 Java 版本。
• 构建工具：本文以 Maven 为例，但同样适用于 Gradle。你可以从 Maven 官方网站下载并安装 Maven，安装完成后，使用命令 mvn -v 验证。
• 集成开发环境（IDE）：如 IntelliJ IDEA 或 Eclipse，能够提高开发效率。

二、Spring Security 基础概念

在深入了解 Spring Security 的配置和用法之前，先理解一些关键概念：

• 认证（Authentication）：验证用户身份的过程，确认用户是否为用户声称的身份。
• 授权（Authorization）：在用户身份经过验证后，确定用户具有执行特定操作或访问特定资源的权限。
• 安全过滤器链（Security Filter Chain）：Spring Security 的核心组件，负责处理认证和授权逻辑，包含多个安全过滤器，按照特定顺序对请求进行处理。
• 上下文（SecurityContext）：存储当前认证用户的信息，可用于在整个请求周期内访问用户相关数据。

三、创建 Spring Boot 项目并引入依赖

创建 Spring Boot 项目

使用 Spring Initializr 可以轻松创建一个新的 Spring Boot 项目。在网页上选择以下配置：

• Project：选择 Maven Project 或 Gradle Project。
• Language：选择 Java。
• Spring Boot：选择最新稳定版本。
• Project Metadata：填写 Group、Artifact 等信息。
• Packaging：选择 Jar。
• Java：选择合适的 Java 版本（推荐 8 或更高）。
1. 添加依赖
在依赖项中选择 Spring Web 和 Spring Security，点击 “Generate” 下载项目压缩包，解压后导入 IDE 开始开发。

四、Spring Security 入门：自动配置与默认设置

添加 Spring Security 依赖后，Spring Boot 会自动配置一个基本的安全机制。启动应用程序，访问任意路径，Spring Security 都会重定向到你默认的登录页面。默认的用户名是 user，密码在应用启动时会输出到控制台。

默认安全配置解析

默认情况下，Spring Security 使用内存身份验证（In-Memory Authentication），并配置了基本的认证规则。这意味着应用启动时，Spring Security 会自动创建一个内置的用户存储，包含一个用户名为 user，密码为一个随机生成的字符串（输出在控制台）的用户。

五、自定义内存用户认证

为了更好地示范，我们可以自定义内存中的用户认证信息。创建一个配置类继承自 WebSecurityConfigurerAdapter，重写 configure 方法来配置用户信息。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {@Overrideprotected void configure(AuthenticationManagerBuilder auth) throws Exception {auth.inMemoryAuthentication().withUser("admin").password(passwordEncoder().encode("admin123")).roles("ADMIN").and().withUser("user").password(passwordEncoder().encode("user123")).roles("USER");}@Overrideprotected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/admin/**").hasRole("ADMIN").antMatchers("/user/**").hasAnyRole("USER", "ADMIN").anyRequest().authenticated().and().formLogin();}@Beanpublic PasswordEncoder passwordEncoder() {return new BCryptPasswordEncoder();}
}

详细解释

@EnableWebSecurity：开启 Spring Security 的安全功能。
configure(AuthenticationManagerBuilder auth)：配置用户认证信息。
• 使用 inMemoryAuthentication() 启用内存中用户存储。
• withUser() 方法定义用户，指定用户名、密码（需要先通过密码编码器编码）和角色。
configure(HttpSecurity http)：配置 HTTP 请求的安全规则。
• authorizeRequests() 开始请求授权配置。
• antMatchers("/admin/**").hasRole("ADMIN") 表示以 /admin/ 开头的路径需要 ADMIN 角色权限。
• antMatchers("/user/**").hasAnyRole("USER", "ADMIN") 表示以 /user/ 开头的路径需要 USER 或 ADMIN 角色权限。
• anyRequest().authenticated() 表示其他所有请求都需要认证。
• formLogin() 启用表单登录方式。
密码编码器：使用 BCryptPasswordEncoder 对密码进行加密存储，提高安全性。

六、基于数据库的用户认证

在实际应用中，用户信息通常存储在数据库中。以下将以 MySQL 数据库为例，演示如何实现基于数据库的用户认证。

1. 数据库设计

创建用户表（user）和角色表（role）以及关联表（user_role）：

CREATE TABLE user (id BIGINT AUTO_INCREMENT PRIMARY KEY,username VARCHAR(50) NOT NULL UNIQUE,password VARCHAR(100) NOT NULL
);CREATE TABLE role (id BIGINT AUTO_INCREMENT PRIMARY KEY,role_name VARCHAR(50) NOT NULL UNIQUE
);CREATE TABLE user_role (user_id BIGINT NOT NULL,role_id BIGINT NOT NULL,PRIMARY KEY (user_id, role_id),FOREIGN KEY (user_id) REFERENCES user(id),FOREIGN KEY (role_id) REFERENCES role(id)
);

2. 实体类定义

创建 JPA 实体类，表示用户和角色：

import javax.persistence.*;
import java.util.Set;@Entity
public class User {@Id@GeneratedValue(strategy = GenerationType.IDENTITY)private Long id;private String username;private String password;@ManyToMany(fetch = FetchType.EAGER)@JoinTable(name = "user_role",joinColumns = @JoinColumn(name = "user_id"),inverseJoinColumns = @JoinColumn(name = "role_id"))private Set<Role> roles;// getters and setters
}@Entity
public class Role {@Id@GeneratedValue(strategy = GenerationType.IDENTITY)private Long id;private String roleName;// getters and setters
}

3. 数据访问层（Repository）

创建 UserRepository 和 RoleRepository：

import org.springframework.data.jpa.repository.JpaRepository;public interface UserRepository extends JpaRepository<User, Long> {User findByUsername(String username);
}public interface RoleRepository extends JpaRepository<Role, Long> {
}

4. 实现 `UserDetailsService`

UserDetailsService 是 Spring Security 用于加载用户信息的核心接口。我们创建一个自定义的实现类：

import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.stereotype.Service;import java.util.HashSet;
import java.util.Set;@Service
public class CustomUserDetailsService implements UserDetailsService {private final UserRepository userRepository;public CustomUserDetailsService(UserRepository userRepository) {this.userRepository = userRepository;}@Overridepublic UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {User user = userRepository.findByUsername(username);if (user == null) {throw new UsernameNotFoundException("User not found");}Set<GrantedAuthority> authorities = new HashSet<>();for (Role role : user.getRoles()) {authorities.add(new SimpleGrantedAuthority("ROLE_" + role.getRoleName()));}return new org.springframework.security.core.userdetails.User(user.getUsername(),user.getPassword(),authorities);}
}

5. 更新安全配置

在 SecurityConfig 类中注入 CustomUserDetailsService 并更新认证配置：

@Override
protected void configure(AuthenticationManagerBuilder auth) throws Exception {auth.userDetailsService(customUserDetailsService).passwordEncoder(passwordEncoder());
}

确保 customUserDetailsService 已经被正确注入到 SecurityConfig 类中。

七、授权管理

Spring Security 提供了灵活的授权机制，允许你基于角色、权限或其他条件来控制资源的访问。

1. 使用注解进行方法级授权

你可以在控制器的方法上使用 @PreAuthorize、@PostAuthorize 等注解来定义细粒度的访问控制规则。

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
public class AdminController {@GetMapping("/admin/dashboard")@PreAuthorize("hasRole('ADMIN')")public String adminDashboard() {return "欢迎来到管理员仪表盘";}
}

2. 在安全配置中定义 URL 级授权

在 SecurityConfig 类的 configure(HttpSecurity http) 方法中，你可以使用表达式语言（SpEL）来定义基于 URL 的访问规则。

@Override
protected void configure(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/admin/**").hasRole("ADMIN").antMatchers("/user/**").hasAnyRole("USER", "ADMIN").anyRequest().authenticated().and().formLogin().loginPage("/login") // 自定义登录页面.permitAll().and().logout().permitAll();
}

3. 自定义权限评估器

对于更复杂的授权需求，你可以实现自定义的 PermissionEvaluator 并将其集成到 Spring Security 中。

八、CSRF 防护

跨站请求伪造（CSRF）是一种常见的网络攻击方式。Spring Security 默认启用了 CSRF 防护机制，它会为每个表单提交生成一个 CSRF 令牌，并在服务器端进行验证。

1. 禁用 CSRF 防护

在某些情况下，如构建 RESTful API 时，你可能需要禁用 CSRF 防护。可以在安全配置中这样做：

@Override
protected void configure(HttpSecurity http) throws Exception {http.csrf().disable()// 其他配置
}

注意：禁用 CSRF 防护会使应用面临风险，建议仅在必要时禁用，并确保其他防护措施到位。

2. 自定义 CSRF 令牌存储

你可以自定义 CSRF 令牌的存储方式，例如将其存储在 HTTP 头中而不是默认的 Cookie 中，以适应特定的应用需求。

九、OAuth2 接入

OAuth2 是一种开放标准，用于授权第三方应用访问用户资源，而无需获取用户的凭证。Spring Security 提供了对 OAuth2 的全面支持，使得集成变得简便。

1. 添加依赖

为了支持 OAuth2 客户端或资源服务器功能，需要在 pom.xml 中添加相应的依赖。

作为 OAuth2 客户端：

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

作为 OAuth2 资源服务器：

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

2. 配置 OAuth2 客户端

假设我们要将应用配置为 OAuth2 客户端，以使用 Google 进行登录。

在 application.properties 中添加配置：

spring.security.oauth2.client.registration.google.client-id=YOUR_GOOGLE_CLIENT_ID
spring.security.oauth2.client.registration.google.client-secret=YOUR_GOOGLE_CLIENT_SECRET
spring.security.oauth2.client.registration.google.redirect-uri={baseUrl}/login/oauth2/code/{registrationId}
spring.security.oauth2.client.provider.google.authorization-uri=https://accounts.google.com/o/oauth2/v2/auth
spring.security.oauth2.client.provider.google.token-uri=https://oauth2.googleapis.com/token
spring.security.oauth2.client.provider.google.user-info-uri=https://www.googleapis.com/oauth2/v3/userinfo
spring.security.oauth2.client.provider.google.user-name-attribute=sub

更新安全配置类以启用 OAuth2 登录：

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.web.SecurityFilterChain;@Configuration
@EnableWebSecurity
public class OAuth2SecurityConfig {@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {http.authorizeRequests(authorizeRequests ->authorizeRequests.antMatchers("/", "/login**").permitAll().anyRequest().authenticated()).oauth2Login(oauth2Login ->oauth2Login.loginPage("/login"));return http.build();}
}

3. 配置 OAuth2 资源服务器

如果你的应用是一个 OAuth2 资源服务器，需要验证传入请求的访问令牌。

在 application.properties 中添加配置：

spring.security.oauth2.resourceserver.jwt.issuer-uri=https://accounts.google.com

更新安全配置类以启用资源服务器：

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.web.SecurityFilterChain;@Configuration
@EnableWebSecurity
public class ResourceServerConfig {@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {http.authorizeRequests(authorizeRequests ->authorizeRequests.antMatchers("/", "/public/**").permitAll().anyRequest().authenticated()).oauth2ResourceServer(oauth2ResourceServer ->oauth2ResourceServer.jwt());return http.build();}
}

4. 自定义 OAuth2 登录流程

你可以自定义 OAuth2 登录后的处理逻辑，例如获取额外的用户信息、映射用户角色等。

创建自定义的 OAuth2UserService：

import org.springframework.security.oauth2.client.userinfo.DefaultOAuth2UserService;
import org.springframework.security.oauth2.client.userinfo.OAuth2UserRequest;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Service;@Service
public class CustomOAuth2UserService extends DefaultOAuth2UserService {@Overridepublic OAuth2User loadUser(OAuth2UserRequest userRequest) throws OAuth2AuthenticationException {OAuth2User user = super.loadUser(userRequest);// 在这里可以添加自定义逻辑，如映射角色、获取额外信息等return user;}
}

在安全配置中注入自定义的 OAuth2UserService：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http, CustomOAuth2UserService customOAuth2UserService) throws Exception {http.authorizeRequests(authorizeRequests ->authorizeRequests.antMatchers("/", "/login**").permitAll().anyRequest().authenticated()).oauth2Login(oauth2Login ->oauth2Login.userInfoEndpoint(userInfoEndpoint ->userInfoEndpoint.userService(customOAuth2UserService)));return http.build();
}