引言

在现代Web开发中，OAuth2已经成为第三方认证与授权的标准协议。通过OAuth2，我们可以让用户使用Google、GitHub或微信等账号登录我们的应用，无需单独注册，同时还能安全地访问受保护的API资源。Spring Security提供了强大的OAuth2支持，从复杂的授权服务器到简洁的客户端配置，都能轻松应对。

本文将聚焦于实战，带你从零搭建一个Spring Boot应用，集成GitHub OAuth2登录，并保护自己的REST API。你将获得一份可直接运行的代码，深入理解OAuth2的授权码流程，并掌握常见问题的解决方案。

---

一、核心概念速览

OAuth2定义了四个核心角色：
- 资源所有者（Resource Owner）：通常就是用户。
- 客户端（Client）：你的应用，需要访问用户数据。
- 授权服务器（Authorization Server）：负责认证用户并颁发令牌，如GitHub、Google。
- 资源服务器（Resource Server）：托管受保护资源的服务器，可以是你的后端API。

最常用的授权类型是授权码模式（Authorization Code），也是本文使用的模式。流程如下：
1. 用户访问客户端，客户端重定向到授权服务器。
2. 用户在授权服务器登录并授权。
3. 授权服务器将用户重定向回客户端，并携带一个code。
4. 客户端使用code向授权服务器换取access_token。
5. 客户端使用access_token请求资源服务器，获取用户数据。

Spring Security对OAuth2的封装主要位于spring-security-oauth2-client和spring-security-oauth2-resource-server模块，我们只需通过配置就能快速集成。

---

二、实战：从零构建GitHub登录应用

我们将创建一个Spring Boot应用，包含一个公开首页和一个需要登录才能访问的/user端点，登录方式采用GitHub账号。

2.1 环境准备

• JDK 17+
• Spring Boot 3.2+
• Maven
• 一个GitHub账号（用于注册OAuth App）

2.2 注册GitHub OAuth应用

登录GitHub，进入 Settings -> Developer settings -> OAuth Apps，点击 New OAuth App。
- Application name: 任意名称，如 my-oauth2-demo
- Homepage URL: http://localhost:8080
- Authorization callback URL: http://localhost:8080/login/oauth2/code/github

注册成功后，你会得到Client ID和Client Secret，稍后需要填入配置文件。

2.3 创建Spring Boot项目

使用Spring Initializr生成项目，添加依赖：
- Spring Web
- OAuth2 Client
- Spring Security

手动添加Thymeleaf用于简单页面渲染。最终pom.xml关键依赖如下：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-oauth2-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
</dependencies>

2.4 配置OAuth2客户端

在application.yml中配置GitHub OAuth2信息：

spring:
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: your-client-id
            client-secret: your-client-secret
            scope: user:email, read:user   # 根据需要请求的权限
        provider:
          github:
            authorization-uri: https://github.com/login/oauth/authorize
            token-uri: https://github.com/login/oauth/access_token
            user-info-uri: https://api.github.com/user
            user-name-attribute: login     # GitHub返回的用户JSON中用作用户名的字段

注意：Spring Boot为GitHub、Google等常用提供商标配了默认配置，当registration名称为github时，provider可省略，这里显式写出是为了展示底层映射关系。

2.5 编写安全配置

创建SecurityConfig类，启用OAuth2登录，并定义访问规则：

package com.example.demo.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.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/", "/error").permitAll()  // 公开访问
                .anyRequest().authenticated()               // 其他请求需登录
            )
            .oauth2Login(oauth2 -> oauth2
                .defaultSuccessUrl("/user", true)           // 登录成功后跳转
            );
        return http.build();
    }
}

这里没有配置资源服务器，因为我们只演示客户端登录和获取用户信息，并非保护API。下一节我们会扩展资源服务器功能。

2.6 编写控制器与页面

创建简单的控制器和Thymeleaf模板：

package com.example.demo.controller;

import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;

import java.util.Map;

@Controller
public class HomeController {

    @GetMapping("/")
    public String index() {
        return "index";
    }

    @GetMapping("/user")
    public String user(@AuthenticationPrincipal OAuth2User principal, Model model) {
        Map<String, Object> attributes = principal.getAttributes();
        model.addAttribute("name", attributes.get("login"));       // GitHub用户名
        model.addAttribute("avatar", attributes.get("avatar_url"));
        model.addAttribute("email", attributes.get("email") != null ? attributes.get("email") : "未公开");
        return "user";
    }
}

index.html模板（src/main/resources/templates/index.html）：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>首页</title>
</head>
<body>
    <h1>欢迎访问</h1>
    <p>请先<a href="/oauth2/authorization/github">使用GitHub登录</a></p>
</body>
</html>

user.html模板：

<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>用户中心</title>
</head>
<body>
    <h1>登录成功！</h1>
    <p>GitHub用户名：<span th:text="${name}"></span></p>
    <p>邮箱：<span th:text="${email}"></span></p>
    <img th:src="${avatar}" width="100" />
    <br/>
    <a href="/logout">退出登录</a>
</body>
</html>

2.7 运行与验证

启动应用，访问 http://localhost:8080，点击登录链接，会跳转到GitHub授权页面。授权后重定向回/user，显示你的GitHub头像、用户名和邮箱。至此，第三方登录集成完成。

---

三、进阶：构建资源服务器保护API

如果你的应用不仅需要登录，还需要提供受保护的API给其他服务调用，则可以添加资源服务器配置。

3.1 添加依赖

只需额外引入：

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

3.2 配置JWT验证（针对GitHub不适用，可自建授权服务器）

由于GitHub颁发的访问令牌不是JWT，我们通常需要自建授权服务器或使用支持JWT的提供商。但若仅在同一应用中既做客户端又做资源服务器，可以使用Spring Session + 浏览器Cookie。一个更通用的实战是使用Spring Authorization Server自建授权中心，不过那篇幅太长。

为了演示资源服务器，我们模拟一个场景：保护/api/me端点，要求请求必须携带有效的Bearer Token。我们可以快速启动一个内嵌的授权服务器吗？使用Spring Authorization Server需要额外配置。为了保持简单且可运行，我们在这里展示如何使用GitHub访问令牌保护API（GitHub令牌也能用于调用GitHub API），但我们的资源服务器验证的是自己的JWT。

折衷方案：在同一个应用中，利用Session认证机制保护API端点，并生成一个简单的JWT用于资源服务器演示。虽然这不是标准OAuth2资源服务器，但能展示配置思路。

真正的OAuth2资源服务器：需要令牌签发方为授权服务器。我们可以启动一个Spring Authorization Server，但会使文章过长。因此，我们将资源服务器的配置部分以示例展示，并说明如何接入自建或第三方授权服务器。

配置一个JWT资源服务器示例（假设授权服务器已就绪）：

@Bean
public SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
    http
        .securityMatcher("/api/**")
        .authorizeHttpRequests(auth -> auth
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(oauth2 -> oauth2
            .jwt(Customizer.withDefaults())
        );
    return http.build();
}

并在application.yml中指定JWT公钥端点：

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:9000   # 授权服务器地址

这样，任何请求/api/me且携带由该授权服务器签发的合法JWT才能通过。完整搭建授权服务器可参考Spring Security官方示例。

---

四、常见问题与注意事项

4.1 回调地址不匹配

常见错误：redirect_uri_mismatch。确保在GitHub OAuth App中填写的回调URL与Spring Security生成的完全一致。默认回调路径为：{baseUrl}/login/oauth2/code/{registrationId}。如果应用运行在http://localhost:8080，注册名为github，则回调地址必须是http://localhost:8080/login/oauth2/code/github。

4.2 CSRF保护

Spring Security默认开启CSRF保护。对于纯API的资源服务器可以关闭，但若是浏览器客户端（如本文示例），建议保留。若遇到POST请求403，检查Thymeleaf模板是否包含_csrf token，或在安全配置中局部关闭CSRF（不推荐）。

4.3 单点登录与Session

OAuth2登录成功后，默认会在服务端创建Session，并通过Cookie JSESSIONID维持登录状态。如果扩展到微服务架构，需要考虑Session共享或转而使用无状态的JWT令牌。

4.4 获取更详细的用户信息

GitHub的默认用户信息端点可能不包含邮箱，需要在scope中明确添加user:email，并在配置中声明。然后在OAuth2User的属性中可通过key email获取（如果用户公开邮箱）。私有邮箱需要额外调用https://api.github.com/user/emails，可自定义OAuth2UserService实现。

4.5 注销

Spring Security的/logout端点默认行为是清除Session，但不会通知第三方授权服务器。如需从GitHub注销，需要额外调用GitHub的登出接口，一般应用场景中无需这样做。

---

五、总结

本文通过一个从零开始的示例，完整演示了如何使用Spring Security OAuth2集成GitHub第三方登录，并简要介绍了资源服务器保护API的方式。核心步骤总结如下：

1. 注册OAuth应用获取client-id/secret
2. 添加spring-boot-starter-oauth2-client依赖
3. 在配置文件中填写提供商详情
4. 编写安全配置，启用oauth2Login
5. 通过@AuthenticationPrincipal获取用户信息

Spring Security强大的抽象使OAuth2集成变得异常简单，我们不必关心底层授权码交换的细节。掌握了这个流程，你可以轻松扩展至Google、微信、钉钉等任何标准OAuth2提供商。

完整代码已托管至GitHub（示例仓库地址，此处省略），欢迎克隆运行。 希望这篇文章帮助你在项目中快速落地OAuth2，让认证不再成为阻碍，而成为产品体验的加分项。

注：本文演示的GitHub登录适用于Spring Boot 3.2.x + Spring Security 6.x，不同版本配置可能略有差异，请以官方文档为准。