Spring Boot 如何整合 Spring Boot OAuth2 Client 实现单点登录？

OAuth2 已经成为互联网认证授权的事实标准，无论是接入 GitHub、Google 这类第三方登录，还是对接企业内部的统一认证中心，都绕不开它。Spring 官方为此提供了专门的 starter，让开发者可以用极少的配置完成整个客户端流程。这篇文章就以实际代码为例，完整演示如何在 Spring Boot 项目中整合 OAuth2 Client，并剖析背后的运行机制，让你不仅会用，还知道它为什么这么工作。

一、理解 OAuth2 授权码流程中的角色分工

在动手写代码之前，先把概念理清楚非常必要。OAuth2 协议中定义了四个角色：资源所有者（通常是用户）、客户端（你的应用）、授权服务器和资源服务器。当你整合 Spring Boot OAuth2 Client 时，你的应用扮演的是客户端角色，它自己不做用户名密码校验，而是引导用户去授权服务器完成认证，再拿回一个访问令牌。

整个授权码流程大致分五步：第一步，用户访问你的应用，应用发现用户未登录，将其重定向到授权服务器的登录页面；第二步，用户在授权服务器上输入凭证并确认授权；第三步，授权服务器带着授权码回调你的应用；第四步，你的应用用授权码加上 client-id 和 client-secret 去授权服务器换取 access token；第五步，应用拿着 token 访问资源接口获取用户信息。Spring Security 把这五步全部封装起来了，开发者只需要提供注册信息即可。

很多初学者容易把 OAuth2 和单点登录混为一谈。严格来说，OAuth2 是授权协议，不是认证协议，真正做认证的是构建在它之上的 OpenID Connect 规范。不过 Spring Security 的 oauth2-client 模块同时支持两种场景，配置方式基本一致，落地单点登录时通常选择支持 OIDC 的提供商，这样能直接拿到 id_token 和用户身份信息。

二、快速搭建一个能跑通的 OAuth2 客户端

先创建一个标准的 Spring Boot 工程，建议使用 2.7 以上或者 3.x 版本，对应的 Spring Security 5.x 与 6.x 对 OAuth2 Client 的支持都比较成熟。在 pom.xml 中加入依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>
&ltlt;dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

接下来在 application.yml 中注册客户端信息。以 GitHub 为例，你需要先到 GitHub 的 Developer settings 里创建一个 OAuth App，拿到 client-id 和 client-secret，回调地址填写你自己应用的登录处理路径：

spring:
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: 你的client-id
            client-secret: 你的client-secret
            scope: read:user, user:email
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        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

注意 redirect-uri 中的 {baseUrl} 和 {registrationId} 是占位符，Spring 会自动替换成实际域名和注册名，这样本地开发和线上部署不用改配置。GitHub 和 Google 这类常见提供商，Spring Security 内置了默认的端点信息，其实 provider 段可以省略，这里写出来是为了让你理解每个配置项的含义，对接自建的认证中心时就必须完整填写了。

最后加一个最简单的安全配置，让所有请求都需要认证：

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .anyRequest().authenticated()
            )
            .oauth2Login(Customizer.withDefaults());
        return http.build();
    }
}

启动应用后访问任意接口，会自动跳转到 GitHub 授权页，授权成功后回到应用，此时访问 /oauth2/authorized-registrations 或者写一个接口输出 Authentication 对象，就能看到登录用户的详细信息。整个过程没有写一行处理 token 的代码，这就是 starter 带来的便利。

三、源码层面看 OAuth2LoginAuthenticationFilter 的执行逻辑

配置虽然简单，但作为工程师，理解内部机制才能在出问题时快速定位。核心组件是 OAuth2LoginAuthenticationFilter，它在过滤器链中默认拦截 /login/oauth2/code/* 路径。当授权服务器带着 code 回调时，这个过滤器被触发，它内部委托给 OAuth2LoginAuthenticationProvider 完成两件事：先用授权码换 token，再根据 token 获取用户信息。

换 token 的过程由 DefaultAuthorizationCodeTokenResponseClient 负责，它底层使用 RestTemplate 向 token-uri 发起请求。拿到 access token 之后，认证提供者会调用 OAuth2UserService 去请求 user-info-uri 拉取用户资料，把结果包装成 OAuth2User，再和注册信息组装成 OAuth2AuthenticationToken 放进 SecurityContext，整个会话就此建立。后续请求通过 Session 识别身份，token 本身默认存在服务端内存中。

如果你需要自定义用户信息解析逻辑，比如把第三方用户和本地用户表做绑定，可以注册自己的 OAuth2UserService：

@Bean
public OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
    return userRequest -> {
        OidcUserService delegate = new OidcUserService();
        OidcUser oidcUser = delegate.loadUser(userRequest);
        // 在这里根据 oidcUser 的信息查找或创建本地用户记录
        return new CustomOidcUser(oidcUser, localUserService.loadOrCreate(oidcUser));
    };
}

这样每个用户首次通过第三方登录时，你可以在本地数据库为他创建一条记录，方便后续做权限管理和数据关联。

四、Token 存储与集群环境下的注意事项

默认情况下，OAuth2 Client 相关的状态数据保存在内存里，包括授权请求的缓存和会话。单机运行没问题，一旦部署多实例，就会出现用户在 A 节点发起授权、回调落到 B 节点导致校验失败的经典报错 authorization_request_not_found。原因在于 AuthorizationRequestRepository 默认基于 HttpSession，而 Session 没有共享。

解决方案有两类。第一类是引入 Spring Session 加 Redis，让所有节点共享会话，改动最小；第二类是自定义 AuthorizationRequestRepository，改用基于 Cookie 或 Redis 的实现，把授权请求的序列化数据从 HttpSession 中剥离出来。对于网关转发导致回调地址不一致的场景，还需要配置 RedirectUriBuilder 或者通过 X-Forwarded-Proto 请求头让 Spring 正确推断 baseUrl，否则占位符解析出来的回调地址是 http 而授权中心注册的是 https，直接校验失败。

五、常见踩坑点汇总

整合过程中最常见的问题有几个：一是回调地址不匹配，授权中心注册的 redirect-uri 必须和配置中的完全一致，包括协议、端口和路径；二是 scope 名称写错，不同提供商的 scope 命名差异很大，写错了要么授权页报错，要么拉不到想要的用户字段；三是内网环境无法访问外网的 token 端点，需要为 RestTemplate 配置代理；四是时钟不同步导致 token 校验失败，特别是对接自建的 Keycloak 或 Casdoor 时，服务器时间相差超过几十秒就会出问题。

排查这类问题的技巧是开启 Spring Security 的调试日志，在配置文件中设置 logging.level.org.springframework.security=DEBUG，可以清楚看到每一次重定向和 token 交换的细节。掌握了这些内容之后，无论是接入第三方登录还是搭建企业内部单点登录体系，Spring Boot OAuth2 Client 都能帮你把认证这件事变得轻量而可控。

Spring BootOAuth2 Client单点登录修改时间：2026-09-16 10:50:41