一文搞懂 Spring Boot 集成 OAuth2.0：从零实现第三方登录（附完整代码+避坑指南）-程序员充电站

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！（发点评论可以给博主加热度哦）

🌟 一、需求场景：为什么我们要用 OAuth2.0？

想象一下这些场景：

用户不想注册账号，只想用微信/支付宝/Google 快速登录你的网站；
你的 App 需要调用 GitHub API 获取用户仓库信息；
公司内部多个系统（如 HR 系统、OA 系统）希望统一登录，避免重复输入账号密码。

这些问题的通用解决方案就是OAuth2.0—— 一种安全、标准的授权框架。

⚠️ 注意：OAuth2.0 是「授权」协议，不是「认证」协议。但它常被用于实现“第三方登录”（如微信登录），此时结合了 OpenID Connect（OIDC）等扩展。

在 Spring Boot 中，我们可以通过spring-boot-starter-oauth2-client轻松集成主流平台（如 GitHub、Google、微信等）的 OAuth2 登录功能。

🧱 二、正例：Spring Boot + OAuth2.0 实现 GitHub 第三方登录

✅ 步骤 1：创建 Spring Boot 项目

依赖如下（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-thymeleaf</artifactId> </dependency> </dependencies>

✅ 步骤 2：配置 application.yml

spring: security: oauth2: client: registration: github: client-id: YOUR_GITHUB_CLIENT_ID client-secret: YOUR_GITHUB_CLIENT_SECRET scope: 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: id

🔑 如何获取client-id和client-secret？
登录 GitHub Developer Settings
创建新 OAuth App
回调地址填：http://localhost:8080/login/oauth2/code/github

✅ 步骤 3：配置 Security 安全策略

@Configuration @EnableWebSecurity public class SecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz .requestMatchers("/", "/login**").permitAll() .anyRequest().authenticated() ) .oauth2Login(oauth2 -> oauth2 .loginPage("/login") // 自定义登录页（可选） .defaultSuccessUrl("/profile", true) // 登录成功跳转 ); return http.build(); } }

✅ 步骤 4：创建控制器和页面

@Controller public class HomeController { @GetMapping("/") public String home() { return "index"; } @GetMapping("/profile") public String profile(Model model, OAuth2AuthenticationToken authentication) { if (authentication != null) { Map<String, Object> attributes = authentication.getPrincipal().getAttributes(); model.addAttribute("name", attributes.get("name")); model.addAttribute("avatar", attributes.get("avatar_url")); } return "profile"; } }

templates/index.html：

<!DOCTYPE html> <html> <head><title>首页</title></head> <body> <h1>欢迎来到我的网站</h1> <a href="/oauth2/authorization/github">使用 GitHub 登录</a> </body> </html>

templates/profile.html：

<!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head><title>个人资料</title></head> <body> <h1>你好，<span th:text="${name}">User</span>！</h1> <img th:src="${avatar}" width="100" /> <a href="/logout">退出登录</a> </body> </html>

✅ 启动项目

访问http://localhost:8080→ 点击“使用 GitHub 登录” → 跳转到 GitHub 授权页 → 授权后返回你的/profile页面，显示用户名和头像！

❌ 三、反例：常见错误写法（千万别这么干！）

反例 1：把 client-secret 写死在代码里

// ❌ 千万不要这样！ @Bean public ClientRegistrationRepository clientRegistrationRepository() { ClientRegistration github = ClientRegistration.withRegistrationId("github") .clientId("your_real_id") .clientSecret("your_real_secret") // ← 泄露风险极高！ .build(); return new InMemoryClientRegistrationRepository(github); }

💡 正确做法：使用application.yml+ 环境变量或配置中心（如 Nacos、Apollo），生产环境绝不能明文写密钥！

反例 2：忽略 HTTPS（生产环境大忌）

OAuth2.0 的回调地址在 GitHub 等平台强制要求 HTTPS（本地 localhost 除外）。

如果你部署到公网却用 HTTP，会报错：

The redirect_uri MUST match the registered callback URL

✅ 解决方案：部署时务必配 HTTPS，或使用 Ngrok / Cloudflare Tunnel 临时测试。

反例 3：未处理用户拒绝授权

用户点击“Cancel”后，GitHub 会重定向到你的回调地址并带上error=access_denied。

如果你没处理，可能报 500 错误。

✅ 建议：自定义失败处理器

.oauth2Login(oauth2 -> oauth2 .failureHandler((request, response, exception) -> { response.sendRedirect("/login?error=oauth_failed"); }) )

⚠️ 四、注意事项（小白必看！）

问题	说明
OAuth2 ≠ JWT	OAuth2 是授权框架，JWT 是令牌格式，二者常搭配但不等同
scope 权限最小化	只申请必要权限（如 GitHub 用`read:user`而非`user`）
state 参数防 CSRF	Spring Security 默认已启用，无需手动处理
用户信息字段不同	GitHub 返回`id`、`name`、`avatar_url`；Google 返回`sub`、`email`、`picture`，注意`user-name-attribute`配置
多平台支持	可同时配置 GitHub、Google、微信（需自定义 Provider）