1. 项目概述为什么我们需要 OAuth2.0 JWT 的组合拳如果你正在开发一个需要用户登录的Web应用尤其是那种“使用微信/QQ/微博账号快速登录”的场景那你一定绕不开OAuth2.0。但光有OAuth2.0还不够它只管授权不管后续的会话管理。这时候JWT就该登场了。这个组合几乎是现代分布式微服务架构下处理用户认证与授权的“黄金搭档”。简单来说OAuth2.0解决的是“用户允许第三方应用访问其存储在资源服务器上的特定资源而无需分享其用户名和密码”的问题。比如你开发了一个健身App想获取用户在微信运动里的步数OAuth2.0就是那个让你在不拿到用户微信密码的前提下合法获取步数数据的协议。而JWTJSON Web Token则是一种轻量级的、自包含的令牌格式它把用户身份信息、权限等数据编码成一个字符串服务端无需查询数据库通过验证签名就能确认令牌的有效性和持有者身份完美解决了分布式系统的会话状态共享难题。我见过不少项目要么只用了OAuth2.0授权后还用传统的Session-Cookie机制导致服务无法水平扩展要么自己拍脑袋设计了一套Token方案安全漏洞百出。所以今天我们就来彻底搞懂这套组合拳并用SpringBoot把它们整合起来让你能直接应用到自己的项目中。2. 核心原理深度拆解OAuth2.0的四种授权模式与JWT的“自证清白”2.1 OAuth2.0不仅仅是“扫码登录”很多人一提到OAuth2.0就想到扫码登录这只是它授权码模式Authorization Code在Web场景下的一个典型应用。OAuth2.0定义了四种授权模式适用于不同信任级别和能力的客户端。授权码模式Authorization Code这是最安全、最完整的流程也是我们最常用的。它涉及两个关键步骤先通过浏览器跳转获取一个“授权码”再用这个授权码在后端服务器换取访问令牌。这个“授权码”是个短命的、一次性的凭证即使被中间人截获因为没有客户端的client_secret也无法换到真正的令牌。这就像你去银行办业务柜员先给你一张“排队号”授权码你拿着这个号和你的身份证client_secret去窗口才能办理真正的业务换取令牌。这种设计有效防止了令牌在传输过程中被直接窃取。简化模式Implicit这个模式是为纯前端应用如单页应用SPA设计的它直接在浏览器重定向的URL片段#后面中返回访问令牌。因为它跳过了用授权码换令牌的步骤令牌直接暴露在浏览器和重定向URL中安全性较低。随着现代前端安全最佳实践的发展如使用带有后端代理的SPA这个模式已不推荐使用。密码模式Resource Owner Password Credentials用户直接把用户名和密码交给客户端应用客户端应用再用这些凭据去换取令牌。这要求用户对客户端应用有极高的信任例如同一个公司内部的移动App。绝对不要在第三方应用中使用此模式因为它违背了OAuth“不分享密码”的核心原则。客户端凭证模式Client Credentials客户端应用以自己的名义而不是用户的名义向授权服务器申请令牌。这适用于服务器对服务器的通信比如一个后台服务需要调用另一个服务的API而这个API不涉及具体用户数据。注意在实际项目中授权码模式是Web应用的首选密码模式仅用于高度信任的内部系统简化模式应尽量避免客户端凭证模式用于服务间调用。2.2 JWT把会话信息“写”在令牌里传统的Session机制服务端需要存储每个登录用户的会话信息Session Object当用户请求到来时通过Cookie中的Session ID来查找对应的会话。这在集群环境下就成了麻烦你需要引入Redis等外部存储来做Session共享。JWT提供了一种无状态的解决方案。一个JWT令牌由三部分组成用点.分隔Header.Payload.Signature。Header声明令牌类型JWT和签名算法如HS256 RS256。Payload存放实际需要传递的数据也就是“声明”Claims。这里可以放用户ID、用户名、角色、令牌过期时间等。注意Payload只是Base64编码并非加密所以绝对不能存放密码等敏感信息。Signature签名部分。这是JWT防篡改的关键。服务器使用Header中声明的算法用一个只有自己知道的密钥Secret或私钥对Header.Payload两部分进行签名。只要密钥不泄露任何人篡改了Payload内容签名验证都会失败。当客户端如浏览器拿到JWT后后续的每次请求都在HTTP Header通常是Authorization: Bearer token中带上它。资源服务器收到后用同样的密钥验证签名。验证通过就说明这个令牌是合法的、未被篡改的可以直接解析Payload获取用户信息无需查询任何数据库或Session存储。它的优势很明显无状态、适合分布式、Payload可自定义。但缺点也需要注意令牌一旦签发在有效期内无法主动使其失效除非使用黑名单机制但这又引入了状态Payload内容不宜过大因为每次请求都要携带。3. 环境准备与项目骨架搭建3.1 技术栈选型与依赖引入我们使用SpringBoot 2.7.x一个稳定版本作为基础框架。核心依赖除了SpringBoot Starter Web主要围绕Spring Security OAuth2和JWT。在pom.xml中我们需要引入以下关键依赖dependencies !-- SpringBoot Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring Security (OAuth2 授权服务器和资源服务器构建在其之上) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency !-- Spring Security OAuth2 授权服务器 -- dependency groupIdorg.springframework.security/groupId artifactIdspring-security-oauth2-authorization-server/artifactId version0.3.1/version !-- 请使用与SpringBoot版本兼容的最新版 -- /dependency !-- JJWT (Java JWT库) 用于生成和解析JWT -- dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.11.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.11.5/version scoperuntime/scope /dependency !-- 数据库和JPA (用于存储用户、客户端信息非必须但建议有) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency /dependencies这里有个关键点Spring官方已将OAuth2授权服务器的支持从Spring Cloud Security中剥离形成了独立的spring-security-oauth2-authorization-server项目。我们直接使用这个官方项目来构建授权服务器它比老旧的spring-security-oauth2-autoconfigure更现代、更符合规范。3.2 项目基础结构设计我们的Demo项目将模拟一个简单的场景一个第三方“天气查询客户端”想要获取用户在“用户中心服务”的基本信息。为此我们需要搭建两个服务授权服务器 (Auth Server)负责用户认证、颁发令牌这里颁发JWT格式的令牌。资源服务器 (Resource Server)提供受保护的API如/userinfo负责验证JWT令牌并返回资源。为了简化我们把授权服务器和资源服务器放在同一个SpringBoot应用中但它们逻辑上是分离的。项目目录结构大致如下src/main/java/com/example/demo/ ├── auth │ ├── config │ │ ├── AuthorizationServerConfig.java // 授权服务器配置 │ │ ├── ResourceServerConfig.java // 资源服务器配置 │ │ └── SecurityConfig.java // 全局安全配置 │ ├── controller │ │ └── UserController.java // 暴露用户信息接口 │ ├── entity │ │ ├── Client.java // 客户端实体 │ │ └── User.java // 用户实体 │ ├── repository // 数据访问层 │ └── service │ └── JwtTokenService.java // JWT生成与解析服务 └── DemoApplication.java // 启动类4. 授权服务器核心配置与JWT令牌定制4.1 配置授权服务器AuthorizationServerConfig这是整个流程的心脏。我们需要在这里注册客户端、配置授权端点、并指定令牌的生成方式为JWT。Configuration EnableAuthorizationServer // 启用授权服务器 public class AuthorizationServerConfig extends AuthorizationServerConfigurerAdapter { Autowired private AuthenticationManager authenticationManager; // 用于密码模式 Autowired private DataSource dataSource; // 用于存储客户端信息到数据库可选 Autowired private JwtTokenService jwtTokenService; // 我们自定义的JWT服务 // 配置客户端详情服务 Override public void configure(ClientDetailsServiceConfigurer clients) throws Exception { // 使用内存存储客户端信息生产环境建议用数据库 clients.inMemory() .withClient(weather-client) // 客户端ID .secret(passwordEncoder().encode(client-secret)) // 客户端密钥必须加密 .authorizedGrantTypes(authorization_code, refresh_token, password) // 支持的授权类型 .scopes(read_userinfo) // 授权范围 .redirectUris(http://localhost:8080/login/oauth2/code/weather) // 授权码模式回调地址 .accessTokenValiditySeconds(3600) // 访问令牌有效期1小时 .refreshTokenValiditySeconds(86400); // 刷新令牌有效期1天 } // 配置授权端点与令牌端点 Override public void configure(AuthorizationServerEndpointsConfigurer endpoints) { endpoints .authenticationManager(authenticationManager) // 支持密码模式 .tokenStore(tokenStore()) // 令牌存储方式这里用JWT存储无状态 .accessTokenConverter(jwtAccessTokenConverter()) // 设置JWT转换器 .allowedTokenEndpointRequestMethods(HttpMethod.POST); } // 配置授权端点的安全约束比如哪些端点需要认证 Override public void configure(AuthorizationServerSecurityConfigurer security) { security .tokenKeyAccess(permitAll()) // /oauth/token_key 公开用于获取JWT签名公钥 .checkTokenAccess(isAuthenticated()) // /oauth/check_token 需要认证 .allowFormAuthenticationForClients(); // 允许客户端使用表单认证 } // 定义令牌存储为JWT Bean public TokenStore tokenStore() { return new JwtTokenStore(jwtAccessTokenConverter()); } // 配置JWT转换器这是定制JWT内容的关键 Bean public JwtAccessTokenConverter jwtAccessTokenConverter() { JwtAccessTokenConverter converter new JwtAccessTokenConverter() { // 增强JWT的Payload添加自定义信息 Override public OAuth2AccessToken enhance(OAuth2AccessToken accessToken, OAuth2Authentication authentication) { // 调用父类方法生成基础的JWT OAuth2AccessToken enhancedToken super.enhance(accessToken, authentication); if (enhancedToken instanceof DefaultOAuth2AccessToken) { DefaultOAuth2AccessToken token (DefaultOAuth2AccessToken) enhancedToken; // 获取用户主体信息 Object principal authentication.getUserAuthentication().getPrincipal(); if (principal instanceof UserDetails) { UserDetails userDetails (UserDetails) principal; // 在JWT的additionalInformation中添加自定义字段 MapString, Object info new HashMap(); info.put(custom_field, This is my custom data); info.put(user_id, userDetails.getUsername()); // 例如加入用户ID token.setAdditionalInformation(info); } } return enhancedToken; } }; // 设置签名密钥用于签名和验证。生产环境建议使用非对称加密RS256这里用对称密钥演示 converter.setSigningKey(my-secret-key-which-should-be-very-long-and-secure-in-production); return converter; } Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }关键点解析withClient和secret这是OAuth2.0中的客户端凭证。secret必须加密存储这里我们用BCrypt加密。在真实场景中这个secret是第三方应用和你授权服务器之间的共享秘密。authorizedGrantTypes定义了该客户端可以使用的授权模式。我们这里开启了授权码、刷新令牌和密码模式。scopes作用域用来限制客户端的权限。客户端申请令牌时必须声明需要的scope用户授权时也会看到这个scope。资源服务器可以根据scope来进一步控制接口访问。JwtAccessTokenConverter这是将标准的OAuth2访问令牌转换为JWT的关键组件。我们重写了enhance方法可以在生成的JWT Payload中加入我们需要的任何自定义信息如用户ID、部门等这些信息后续在资源服务器可以直接解析出来使用。4.2 自定义JWT令牌服务JwtTokenService虽然JwtAccessTokenConverter能生成JWT但有时我们需要更灵活地生成或解析JWT例如在资源服务器手动解析。我们可以封装一个工具类。Service public class JwtTokenService { private final SecretKey secretKey Keys.hmacShaKeyFor( my-secret-key-which-should-be-very-long-and-secure-in-production.getBytes(StandardCharsets.UTF_8) ); // 生成一个自定义的JWT非OAuth2流程用于演示 public String generateToken(String username, ListString roles) { return Jwts.builder() .setSubject(username) .claim(roles, roles) // 自定义声明 .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() 3600 * 1000)) // 1小时过期 .signWith(secretKey, SignatureAlgorithm.HS256) .compact(); } // 解析并验证JWT public Claims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(secretKey) .build() .parseClaimsJws(token) .getBody(); } // 从JWT中提取用户名 public String getUsernameFromToken(String token) { return parseToken(token).getSubject(); } }这个服务使用了jjwt库它提供了流畅的API来创建和解析JWT。注意签名密钥secretKey需要与授权服务器中JwtAccessTokenConverter设置的signingKey保持一致否则资源服务器无法验证令牌。5. 资源服务器配置与接口保护授权服务器颁发了JWT令牌资源服务器的职责就是验证这个令牌并允许或拒绝访问受保护的资源。5.1 配置资源服务器ResourceServerConfigConfiguration EnableResourceServer // 启用资源服务器 public class ResourceServerConfig extends ResourceServerConfigurerAdapter { Autowired private JwtTokenService jwtTokenService; // 用于令牌解析 // 配置资源服务器的安全规则 Override public void configure(HttpSecurity http) throws Exception { http .authorizeRequests() .antMatchers(/oauth/**).permitAll() // 授权相关端点公开 .antMatchers(/userinfo).hasAuthority(SCOPE_read_userinfo) // 需要特定scope .antMatchers(/admin/**).hasRole(ADMIN) // 需要特定角色注意角色前缀 .anyRequest().authenticated() // 其他所有请求都需要认证 .and() .csrf().disable(); // 通常API服务禁用CSRF } // 配置资源服务器的令牌服务告诉它如何解析和验证令牌 Override public void configure(ResourceServerSecurityConfigurer resources) { resources.tokenServices(tokenServices()); } // 定义令牌服务使用我们自定义的JWT令牌存储 Bean public ResourceServerTokenServices tokenServices() { // 使用RemoteTokenServices可以调用授权服务器的/oauth/check_token端点验证令牌 // 但对于JWT我们更常用本地验证因为JWT是自包含的。 // 这里我们使用DefaultTokenServices并配置一个JWT TokenStore DefaultTokenServices defaultTokenServices new DefaultTokenServices(); defaultTokenServices.setTokenStore(tokenStore()); return defaultTokenServices; } Bean public TokenStore tokenStore() { // 这里的JwtAccessTokenConverter必须和授权服务器的配置一致相同的签名密钥 JwtAccessTokenConverter converter new JwtAccessTokenConverter(); converter.setSigningKey(my-secret-key-which-should-be-very-long-and-secure-in-production); return new JwtTokenStore(converter); } }关键点解析EnableResourceServer这个注解会为应用添加一个过滤器链优先级在Spring Security的主过滤器链之前专门用于处理OAuth2令牌认证。hasAuthority(SCOPE_read_userinfo)这里检查的是scope。在OAuth2中scope会被转换为带有SCOPE_前缀的权限。这意味着客户端申请的令牌必须包含read_userinfo这个scope才能访问/userinfo接口。hasRole(ADMIN)检查的是用户角色。角色信息通常来自JWT Payload中的authorities或roles声明或者通过自定义的UserDetailsService加载。注意Spring Security默认会给角色名加上ROLE_前缀所以数据库中存储的可能是ADMIN但这里检查的是ROLE_ADMIN。我们可以在JWT生成时处理好这个前缀。tokenStore()资源服务器也需要一个TokenStore来“理解”令牌。我们同样配置一个JwtTokenStore并使用完全相同的签名密钥。这样资源服务器就能本地验证JWT的签名而无需每次请求都去授权服务器验证极大地提高了性能。5.2 实现受保护的资源接口现在我们来创建一个简单的受保护接口。RestController public class UserController { GetMapping(/userinfo) public MapString, Object getUserInfo(AuthenticationPrincipal Jwt jwt) { // 通过AuthenticationPrincipal注解可以直接注入解析后的JWT对象 String username jwt.getSubject(); String customField jwt.getClaimAsString(custom_field); // 获取自定义字段 CollectionString scopes jwt.getClaimAsStringList(scope); // 获取scope MapString, Object userInfo new HashMap(); userInfo.put(username, username); userInfo.put(custom_field, customField); userInfo.put(scopes, scopes); userInfo.put(message, This is your protected user info.); return userInfo; } GetMapping(/admin/dashboard) public String adminDashboard() { return Welcome to Admin Dashboard!; } }这里展示了两种获取用户信息的方式注入Jwt对象这是Spring Security OAuth2资源服务器提供的便捷方式当令牌是JWT时可以直接拿到解析后的对象方便地获取其中的声明Claims。你也可以注入Authentication对象然后从principal中获取信息。AuthenticationPrincipal注解非常有用它帮我们完成了从HTTP请求头中提取令牌、验证签名、解析JWT这一系列复杂操作。6. 全局安全与用户详情配置授权服务器和资源服务器都需要对用户进行认证比如密码模式、授权码模式中用户的登录。我们需要配置一个全局的SecurityConfig来定义用户如何登录。Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } Bean Override public AuthenticationManager authenticationManagerBean() throws Exception { return super.authenticationManagerBean(); } Override protected void configure(HttpSecurity http) throws Exception { http .authorizeRequests() .antMatchers(/, /login**, /error**).permitAll() .anyRequest().authenticated() .and() .formLogin() // 启用表单登录用于授权服务器的用户登录页面 .and() .csrf().disable(); } // 配置内存中的用户生产环境从数据库加载 Override protected void configure(AuthenticationManagerBuilder auth) throws Exception { auth.inMemoryAuthentication() .withUser(user) .password(passwordEncoder().encode(password)) .roles(USER) .and() .withUser(admin) .password(passwordEncoder().encode(admin)) .roles(ADMIN, USER); } }这个配置做了几件事定义了密码编码器BCryptPasswordEncoder确保密码安全存储。暴露了AuthenticationManagerBean这是授权服务器在密码模式下所必需的。配置了HTTP安全规则允许访问登录页和错误页其他请求需要认证。并启用了表单登录这样当用户通过浏览器访问授权端点时会跳转到Spring Security默认的登录页。在内存中创建了两个测试用户user和admin并赋予了不同的角色。实操心得在生产环境中configure(AuthenticationManagerBuilder auth)这部分一定要替换为从数据库查询用户的UserDetailsService实现。内存用户仅用于开发和测试。7. 完整OAuth2授权码模式流程实战演示现在让我们启动应用默认端口8080并模拟一个完整的授权码模式流程。为了测试我们可以使用任何支持OAuth2的客户端或者直接用浏览器和命令行工具如curl。7.1 第一步用户授权请求第三方天气客户端client_id:weather-client想要获取用户信息它会将用户重定向到授权服务器的授权端点http://localhost:8080/oauth/authorize?response_typecodeclient_idweather-clientredirect_urihttp://localhost:8080/login/oauth2/code/weatherscoperead_userinfo在浏览器中访问这个URL你会被重定向到登录页面由我们上面的SecurityConfig提供。使用user/password登录。登录成功后你会看到授权确认页面Spring OAuth2默认提供询问用户是否授权weather-client访问你的read_userinfo信息。点击“Authorize”。7.2 第二步获取授权码授权成功后浏览器会被重定向到我们预先注册的redirect_uri并且URL中会附带一个code参数http://localhost:8080/login/oauth2/code/weather?codeMs3DcU这个code是随机的。这个code就是授权码它有效期很短通常几分钟且只能使用一次。7.3 第三步用授权码换取访问令牌第三方客户端应用必须在自己的服务器后端拿到这个code后向授权服务器的令牌端点发起一个POST请求换取访问令牌。这一步不能在浏览器前端完成因为需要传递client_secret。使用curl命令模拟curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeauthorization_codecodeMs3DcUredirect_urihttp://localhost:8080/login/oauth2/code/weather参数解释-H Authorization: Basic ...这是HTTP Basic认证头用于传递客户端凭证。d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA是weather-client:client-secret的Base64编码。grant_typeauthorization_code声明使用授权码模式。code上一步获取的授权码。redirect_uri必须与申请授权码时使用的redirect_uri完全一致。7.4 第四步收到访问令牌和刷新令牌如果一切正常授权服务器会返回一个JSON响应{ access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...很长的一串JWT..., token_type: bearer, expires_in: 3599, scope: read_userinfo, custom_field: This is my custom data, user_id: user, jti: e2a3b1c0-5f8e-4a2b-9c7d-6e5f4a3b2c1d }注意access_token就是一个JWT字符串。响应里还包含了我们自定义的字段custom_field和user_id。同时由于我们在客户端配置中启用了refresh_token响应中也会包含一个refresh_token。7.5 第五步使用访问令牌调用受保护接口现在第三方客户端就可以用这个access_token去调用资源服务器的/userinfo接口了。curl -X GET \ http://localhost:8080/userinfo \ -H Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...在Header中设置Authorization: Bearer access_token。如果令牌有效且scope正确资源服务器将返回{ username: user, custom_field: This is my custom data, scopes: [read_userinfo], message: This is your protected user info. }至此一个完整的OAuth2.0授权码模式 JWT令牌的流程就跑通了。8. 密码模式与刷新令牌实战8.1 密码模式快速获取令牌对于高度信任的客户端如自家开发的手机App可以使用密码模式。客户端直接收集用户的用户名和密码向令牌端点申请令牌。curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typepasswordusernameuserpasswordpasswordscoperead_userinfo参数变成了grant_typepassword并直接传递username和password。返回的令牌格式与授权码模式相同。重要警告再次强调此模式仅限受信任的第一方客户端使用。将用户密码交给第三方应用是极其危险的行为。8.2 使用刷新令牌获取新的访问令牌访问令牌有效期较短如1小时过期后需要重新获取。为了避免让用户再次登录可以使用刷新令牌。curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typerefresh_tokenrefresh_tokenyour_refresh_token将grant_type设为refresh_token并附上之前获取的refresh_token。成功后会返回一个新的access_token和新的refresh_token刷新令牌通常也是单次使用的或者有滚动更新策略。9. 常见问题、排查技巧与进阶优化在实际整合中你肯定会遇到各种坑。下面是我踩过的一些坑和解决方案。9.1 常见错误码与排查invalid_client: 客户端认证失败。检查client_id和client_secret是否正确HTTP Basic认证头的格式是否正确Base64(client_id:client_secret)以及client_secret在数据库中是否加密存储比较时是否用了正确的PasswordEncoder。invalid_grant: 授权失败。在授权码模式下检查code是否有效、是否已使用过、是否过期以及redirect_uri是否与申请code时完全一致。在密码模式下检查用户名密码是否正确。invalid_token: 资源服务器报告令牌无效。99%的情况是签名验证失败。确保授权服务器和资源服务器使用的JWT签名密钥signingKey完全一致。如果是RS256非对称加密则要确保资源服务器配置的是授权服务器的公钥。insufficient_scope: 访问资源时权限不足。检查请求的接口所需的scope如SCOPE_read_userinfo与令牌中包含的scope是否匹配。在JwtAccessTokenConverter.enhance方法中确保scope被正确写入JWT。Unauthorized401错误: 可能根本没传Authorization头或者令牌已过期。检查网络请求的Header。9.2 JWT相关的最佳实践与坑密钥管理演示用的对称密钥HS256不安全。生产环境务必使用非对称加密RS256。授权服务器用私钥签名资源服务器用公钥验证。公钥可以公开私钥必须严格保护。令牌失效问题JWT一旦签发在过期前无法主动失效。如果需要实现“登出即失效”可以引入一个短期的令牌黑名单Redis登出时将未过期的令牌IDJWT中的jti字段加入黑名单并设置一个较短的TTL。资源服务器在验证签名后再查一下黑名单。不要存放敏感信息JWT的Payload只是Base64编码任何人都可以解码看到。千万不要把密码、手机号等敏感信息放进去。控制Payload大小JWT会被放在每次请求的Header里太大会增加网络开销。只放必要的用户标识和权限信息。时钟偏移服务器之间可能存在微小的时间差可能导致令牌在“过期时间”之前或之后被误判。可以在验证时允许一个小的时钟偏移容差jjwt库支持setAllowedClockSkewSeconds。9.3 进阶优化方向自定义登录页和授权确认页Spring Security默认的页面很丑。你可以通过实现WebSecurityConfigurerAdapter并配置formLogin().loginPage(“/my-login”)来自定义登录页。授权确认页则需要自定义AuthorizationServerEndpointsConfigurer的pathMapping或实现自己的UserApprovalHandler。数据库存储客户端与用户信息将ClientDetailsService和UserDetailsService的实现连接到你的用户表、客户端表。JdbcClientDetailsService和JdbcUserDetailsManager可以帮你快速实现。令牌增强与自定义Claim就像我们在JwtAccessTokenConverter.enhance里做的那样你可以把更多业务需要的用户信息如部门ID、头像URL放入JWT这样资源服务器就无需查用户库。整合Spring Cloud Gateway在微服务架构中通常会在网关层统一进行JWT验证和鉴权而不是在每个资源服务里都配一遍。可以在Gateway中配置一个全局过滤器来解析和验证JWT并将用户信息传递给下游服务。监控与审计记录令牌的颁发、使用和刷新日志对于安全审计和问题排查非常有帮助。整合OAuth2.0和JWT初看配置繁多但一旦理清“授权服务器”、“资源服务器”、“客户端”这三者的关系以及“授权码”、“访问令牌”、“刷新令牌”的流转过程就会豁然开朗。这套组合为构建安全、可扩展的现代应用提供了坚实的基础设施。
1. 项目概述为什么我们需要 OAuth2.0 JWT 的组合拳如果你正在开发一个需要用户登录的Web应用尤其是那种“使用微信/QQ/微博账号快速登录”的场景那你一定绕不开OAuth2.0。但光有OAuth2.0还不够它只管授权不管后续的会话管理。这时候JWT就该登场了。这个组合几乎是现代分布式微服务架构下处理用户认证与授权的“黄金搭档”。简单来说OAuth2.0解决的是“用户允许第三方应用访问其存储在资源服务器上的特定资源而无需分享其用户名和密码”的问题。比如你开发了一个健身App想获取用户在微信运动里的步数OAuth2.0就是那个让你在不拿到用户微信密码的前提下合法获取步数数据的协议。而JWTJSON Web Token则是一种轻量级的、自包含的令牌格式它把用户身份信息、权限等数据编码成一个字符串服务端无需查询数据库通过验证签名就能确认令牌的有效性和持有者身份完美解决了分布式系统的会话状态共享难题。我见过不少项目要么只用了OAuth2.0授权后还用传统的Session-Cookie机制导致服务无法水平扩展要么自己拍脑袋设计了一套Token方案安全漏洞百出。所以今天我们就来彻底搞懂这套组合拳并用SpringBoot把它们整合起来让你能直接应用到自己的项目中。2. 核心原理深度拆解OAuth2.0的四种授权模式与JWT的“自证清白”2.1 OAuth2.0不仅仅是“扫码登录”很多人一提到OAuth2.0就想到扫码登录这只是它授权码模式Authorization Code在Web场景下的一个典型应用。OAuth2.0定义了四种授权模式适用于不同信任级别和能力的客户端。授权码模式Authorization Code这是最安全、最完整的流程也是我们最常用的。它涉及两个关键步骤先通过浏览器跳转获取一个“授权码”再用这个授权码在后端服务器换取访问令牌。这个“授权码”是个短命的、一次性的凭证即使被中间人截获因为没有客户端的client_secret也无法换到真正的令牌。这就像你去银行办业务柜员先给你一张“排队号”授权码你拿着这个号和你的身份证client_secret去窗口才能办理真正的业务换取令牌。这种设计有效防止了令牌在传输过程中被直接窃取。简化模式Implicit这个模式是为纯前端应用如单页应用SPA设计的它直接在浏览器重定向的URL片段#后面中返回访问令牌。因为它跳过了用授权码换令牌的步骤令牌直接暴露在浏览器和重定向URL中安全性较低。随着现代前端安全最佳实践的发展如使用带有后端代理的SPA这个模式已不推荐使用。密码模式Resource Owner Password Credentials用户直接把用户名和密码交给客户端应用客户端应用再用这些凭据去换取令牌。这要求用户对客户端应用有极高的信任例如同一个公司内部的移动App。绝对不要在第三方应用中使用此模式因为它违背了OAuth“不分享密码”的核心原则。客户端凭证模式Client Credentials客户端应用以自己的名义而不是用户的名义向授权服务器申请令牌。这适用于服务器对服务器的通信比如一个后台服务需要调用另一个服务的API而这个API不涉及具体用户数据。注意在实际项目中授权码模式是Web应用的首选密码模式仅用于高度信任的内部系统简化模式应尽量避免客户端凭证模式用于服务间调用。2.2 JWT把会话信息“写”在令牌里传统的Session机制服务端需要存储每个登录用户的会话信息Session Object当用户请求到来时通过Cookie中的Session ID来查找对应的会话。这在集群环境下就成了麻烦你需要引入Redis等外部存储来做Session共享。JWT提供了一种无状态的解决方案。一个JWT令牌由三部分组成用点.分隔Header.Payload.Signature。Header声明令牌类型JWT和签名算法如HS256 RS256。Payload存放实际需要传递的数据也就是“声明”Claims。这里可以放用户ID、用户名、角色、令牌过期时间等。注意Payload只是Base64编码并非加密所以绝对不能存放密码等敏感信息。Signature签名部分。这是JWT防篡改的关键。服务器使用Header中声明的算法用一个只有自己知道的密钥Secret或私钥对Header.Payload两部分进行签名。只要密钥不泄露任何人篡改了Payload内容签名验证都会失败。当客户端如浏览器拿到JWT后后续的每次请求都在HTTP Header通常是Authorization: Bearer token中带上它。资源服务器收到后用同样的密钥验证签名。验证通过就说明这个令牌是合法的、未被篡改的可以直接解析Payload获取用户信息无需查询任何数据库或Session存储。它的优势很明显无状态、适合分布式、Payload可自定义。但缺点也需要注意令牌一旦签发在有效期内无法主动使其失效除非使用黑名单机制但这又引入了状态Payload内容不宜过大因为每次请求都要携带。3. 环境准备与项目骨架搭建3.1 技术栈选型与依赖引入我们使用SpringBoot 2.7.x一个稳定版本作为基础框架。核心依赖除了SpringBoot Starter Web主要围绕Spring Security OAuth2和JWT。在pom.xml中我们需要引入以下关键依赖dependencies !-- SpringBoot Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring Security (OAuth2 授权服务器和资源服务器构建在其之上) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-security/artifactId /dependency !-- Spring Security OAuth2 授权服务器 -- dependency groupIdorg.springframework.security/groupId artifactIdspring-security-oauth2-authorization-server/artifactId version0.3.1/version !-- 请使用与SpringBoot版本兼容的最新版 -- /dependency !-- JJWT (Java JWT库) 用于生成和解析JWT -- dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-api/artifactId version0.11.5/version /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-impl/artifactId version0.11.5/version scoperuntime/scope /dependency dependency groupIdio.jsonwebtoken/groupId artifactIdjjwt-jackson/artifactId version0.11.5/version scoperuntime/scope /dependency !-- 数据库和JPA (用于存储用户、客户端信息非必须但建议有) -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency /dependencies这里有个关键点Spring官方已将OAuth2授权服务器的支持从Spring Cloud Security中剥离形成了独立的spring-security-oauth2-authorization-server项目。我们直接使用这个官方项目来构建授权服务器它比老旧的spring-security-oauth2-autoconfigure更现代、更符合规范。3.2 项目基础结构设计我们的Demo项目将模拟一个简单的场景一个第三方“天气查询客户端”想要获取用户在“用户中心服务”的基本信息。为此我们需要搭建两个服务授权服务器 (Auth Server)负责用户认证、颁发令牌这里颁发JWT格式的令牌。资源服务器 (Resource Server)提供受保护的API如/userinfo负责验证JWT令牌并返回资源。为了简化我们把授权服务器和资源服务器放在同一个SpringBoot应用中但它们逻辑上是分离的。项目目录结构大致如下src/main/java/com/example/demo/ ├── auth │ ├── config │ │ ├── AuthorizationServerConfig.java // 授权服务器配置 │ │ ├── ResourceServerConfig.java // 资源服务器配置 │ │ └── SecurityConfig.java // 全局安全配置 │ ├── controller │ │ └── UserController.java // 暴露用户信息接口 │ ├── entity │ │ ├── Client.java // 客户端实体 │ │ └── User.java // 用户实体 │ ├── repository // 数据访问层 │ └── service │ └── JwtTokenService.java // JWT生成与解析服务 └── DemoApplication.java // 启动类4. 授权服务器核心配置与JWT令牌定制4.1 配置授权服务器AuthorizationServerConfig这是整个流程的心脏。我们需要在这里注册客户端、配置授权端点、并指定令牌的生成方式为JWT。Configuration EnableAuthorizationServer // 启用授权服务器 public class AuthorizationServerConfig extends AuthorizationServerConfigurerAdapter { Autowired private AuthenticationManager authenticationManager; // 用于密码模式 Autowired private DataSource dataSource; // 用于存储客户端信息到数据库可选 Autowired private JwtTokenService jwtTokenService; // 我们自定义的JWT服务 // 配置客户端详情服务 Override public void configure(ClientDetailsServiceConfigurer clients) throws Exception { // 使用内存存储客户端信息生产环境建议用数据库 clients.inMemory() .withClient(weather-client) // 客户端ID .secret(passwordEncoder().encode(client-secret)) // 客户端密钥必须加密 .authorizedGrantTypes(authorization_code, refresh_token, password) // 支持的授权类型 .scopes(read_userinfo) // 授权范围 .redirectUris(http://localhost:8080/login/oauth2/code/weather) // 授权码模式回调地址 .accessTokenValiditySeconds(3600) // 访问令牌有效期1小时 .refreshTokenValiditySeconds(86400); // 刷新令牌有效期1天 } // 配置授权端点与令牌端点 Override public void configure(AuthorizationServerEndpointsConfigurer endpoints) { endpoints .authenticationManager(authenticationManager) // 支持密码模式 .tokenStore(tokenStore()) // 令牌存储方式这里用JWT存储无状态 .accessTokenConverter(jwtAccessTokenConverter()) // 设置JWT转换器 .allowedTokenEndpointRequestMethods(HttpMethod.POST); } // 配置授权端点的安全约束比如哪些端点需要认证 Override public void configure(AuthorizationServerSecurityConfigurer security) { security .tokenKeyAccess(permitAll()) // /oauth/token_key 公开用于获取JWT签名公钥 .checkTokenAccess(isAuthenticated()) // /oauth/check_token 需要认证 .allowFormAuthenticationForClients(); // 允许客户端使用表单认证 } // 定义令牌存储为JWT Bean public TokenStore tokenStore() { return new JwtTokenStore(jwtAccessTokenConverter()); } // 配置JWT转换器这是定制JWT内容的关键 Bean public JwtAccessTokenConverter jwtAccessTokenConverter() { JwtAccessTokenConverter converter new JwtAccessTokenConverter() { // 增强JWT的Payload添加自定义信息 Override public OAuth2AccessToken enhance(OAuth2AccessToken accessToken, OAuth2Authentication authentication) { // 调用父类方法生成基础的JWT OAuth2AccessToken enhancedToken super.enhance(accessToken, authentication); if (enhancedToken instanceof DefaultOAuth2AccessToken) { DefaultOAuth2AccessToken token (DefaultOAuth2AccessToken) enhancedToken; // 获取用户主体信息 Object principal authentication.getUserAuthentication().getPrincipal(); if (principal instanceof UserDetails) { UserDetails userDetails (UserDetails) principal; // 在JWT的additionalInformation中添加自定义字段 MapString, Object info new HashMap(); info.put(custom_field, This is my custom data); info.put(user_id, userDetails.getUsername()); // 例如加入用户ID token.setAdditionalInformation(info); } } return enhancedToken; } }; // 设置签名密钥用于签名和验证。生产环境建议使用非对称加密RS256这里用对称密钥演示 converter.setSigningKey(my-secret-key-which-should-be-very-long-and-secure-in-production); return converter; } Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }关键点解析withClient和secret这是OAuth2.0中的客户端凭证。secret必须加密存储这里我们用BCrypt加密。在真实场景中这个secret是第三方应用和你授权服务器之间的共享秘密。authorizedGrantTypes定义了该客户端可以使用的授权模式。我们这里开启了授权码、刷新令牌和密码模式。scopes作用域用来限制客户端的权限。客户端申请令牌时必须声明需要的scope用户授权时也会看到这个scope。资源服务器可以根据scope来进一步控制接口访问。JwtAccessTokenConverter这是将标准的OAuth2访问令牌转换为JWT的关键组件。我们重写了enhance方法可以在生成的JWT Payload中加入我们需要的任何自定义信息如用户ID、部门等这些信息后续在资源服务器可以直接解析出来使用。4.2 自定义JWT令牌服务JwtTokenService虽然JwtAccessTokenConverter能生成JWT但有时我们需要更灵活地生成或解析JWT例如在资源服务器手动解析。我们可以封装一个工具类。Service public class JwtTokenService { private final SecretKey secretKey Keys.hmacShaKeyFor( my-secret-key-which-should-be-very-long-and-secure-in-production.getBytes(StandardCharsets.UTF_8) ); // 生成一个自定义的JWT非OAuth2流程用于演示 public String generateToken(String username, ListString roles) { return Jwts.builder() .setSubject(username) .claim(roles, roles) // 自定义声明 .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() 3600 * 1000)) // 1小时过期 .signWith(secretKey, SignatureAlgorithm.HS256) .compact(); } // 解析并验证JWT public Claims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(secretKey) .build() .parseClaimsJws(token) .getBody(); } // 从JWT中提取用户名 public String getUsernameFromToken(String token) { return parseToken(token).getSubject(); } }这个服务使用了jjwt库它提供了流畅的API来创建和解析JWT。注意签名密钥secretKey需要与授权服务器中JwtAccessTokenConverter设置的signingKey保持一致否则资源服务器无法验证令牌。5. 资源服务器配置与接口保护授权服务器颁发了JWT令牌资源服务器的职责就是验证这个令牌并允许或拒绝访问受保护的资源。5.1 配置资源服务器ResourceServerConfigConfiguration EnableResourceServer // 启用资源服务器 public class ResourceServerConfig extends ResourceServerConfigurerAdapter { Autowired private JwtTokenService jwtTokenService; // 用于令牌解析 // 配置资源服务器的安全规则 Override public void configure(HttpSecurity http) throws Exception { http .authorizeRequests() .antMatchers(/oauth/**).permitAll() // 授权相关端点公开 .antMatchers(/userinfo).hasAuthority(SCOPE_read_userinfo) // 需要特定scope .antMatchers(/admin/**).hasRole(ADMIN) // 需要特定角色注意角色前缀 .anyRequest().authenticated() // 其他所有请求都需要认证 .and() .csrf().disable(); // 通常API服务禁用CSRF } // 配置资源服务器的令牌服务告诉它如何解析和验证令牌 Override public void configure(ResourceServerSecurityConfigurer resources) { resources.tokenServices(tokenServices()); } // 定义令牌服务使用我们自定义的JWT令牌存储 Bean public ResourceServerTokenServices tokenServices() { // 使用RemoteTokenServices可以调用授权服务器的/oauth/check_token端点验证令牌 // 但对于JWT我们更常用本地验证因为JWT是自包含的。 // 这里我们使用DefaultTokenServices并配置一个JWT TokenStore DefaultTokenServices defaultTokenServices new DefaultTokenServices(); defaultTokenServices.setTokenStore(tokenStore()); return defaultTokenServices; } Bean public TokenStore tokenStore() { // 这里的JwtAccessTokenConverter必须和授权服务器的配置一致相同的签名密钥 JwtAccessTokenConverter converter new JwtAccessTokenConverter(); converter.setSigningKey(my-secret-key-which-should-be-very-long-and-secure-in-production); return new JwtTokenStore(converter); } }关键点解析EnableResourceServer这个注解会为应用添加一个过滤器链优先级在Spring Security的主过滤器链之前专门用于处理OAuth2令牌认证。hasAuthority(SCOPE_read_userinfo)这里检查的是scope。在OAuth2中scope会被转换为带有SCOPE_前缀的权限。这意味着客户端申请的令牌必须包含read_userinfo这个scope才能访问/userinfo接口。hasRole(ADMIN)检查的是用户角色。角色信息通常来自JWT Payload中的authorities或roles声明或者通过自定义的UserDetailsService加载。注意Spring Security默认会给角色名加上ROLE_前缀所以数据库中存储的可能是ADMIN但这里检查的是ROLE_ADMIN。我们可以在JWT生成时处理好这个前缀。tokenStore()资源服务器也需要一个TokenStore来“理解”令牌。我们同样配置一个JwtTokenStore并使用完全相同的签名密钥。这样资源服务器就能本地验证JWT的签名而无需每次请求都去授权服务器验证极大地提高了性能。5.2 实现受保护的资源接口现在我们来创建一个简单的受保护接口。RestController public class UserController { GetMapping(/userinfo) public MapString, Object getUserInfo(AuthenticationPrincipal Jwt jwt) { // 通过AuthenticationPrincipal注解可以直接注入解析后的JWT对象 String username jwt.getSubject(); String customField jwt.getClaimAsString(custom_field); // 获取自定义字段 CollectionString scopes jwt.getClaimAsStringList(scope); // 获取scope MapString, Object userInfo new HashMap(); userInfo.put(username, username); userInfo.put(custom_field, customField); userInfo.put(scopes, scopes); userInfo.put(message, This is your protected user info.); return userInfo; } GetMapping(/admin/dashboard) public String adminDashboard() { return Welcome to Admin Dashboard!; } }这里展示了两种获取用户信息的方式注入Jwt对象这是Spring Security OAuth2资源服务器提供的便捷方式当令牌是JWT时可以直接拿到解析后的对象方便地获取其中的声明Claims。你也可以注入Authentication对象然后从principal中获取信息。AuthenticationPrincipal注解非常有用它帮我们完成了从HTTP请求头中提取令牌、验证签名、解析JWT这一系列复杂操作。6. 全局安全与用户详情配置授权服务器和资源服务器都需要对用户进行认证比如密码模式、授权码模式中用户的登录。我们需要配置一个全局的SecurityConfig来定义用户如何登录。Configuration EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } Bean Override public AuthenticationManager authenticationManagerBean() throws Exception { return super.authenticationManagerBean(); } Override protected void configure(HttpSecurity http) throws Exception { http .authorizeRequests() .antMatchers(/, /login**, /error**).permitAll() .anyRequest().authenticated() .and() .formLogin() // 启用表单登录用于授权服务器的用户登录页面 .and() .csrf().disable(); } // 配置内存中的用户生产环境从数据库加载 Override protected void configure(AuthenticationManagerBuilder auth) throws Exception { auth.inMemoryAuthentication() .withUser(user) .password(passwordEncoder().encode(password)) .roles(USER) .and() .withUser(admin) .password(passwordEncoder().encode(admin)) .roles(ADMIN, USER); } }这个配置做了几件事定义了密码编码器BCryptPasswordEncoder确保密码安全存储。暴露了AuthenticationManagerBean这是授权服务器在密码模式下所必需的。配置了HTTP安全规则允许访问登录页和错误页其他请求需要认证。并启用了表单登录这样当用户通过浏览器访问授权端点时会跳转到Spring Security默认的登录页。在内存中创建了两个测试用户user和admin并赋予了不同的角色。实操心得在生产环境中configure(AuthenticationManagerBuilder auth)这部分一定要替换为从数据库查询用户的UserDetailsService实现。内存用户仅用于开发和测试。7. 完整OAuth2授权码模式流程实战演示现在让我们启动应用默认端口8080并模拟一个完整的授权码模式流程。为了测试我们可以使用任何支持OAuth2的客户端或者直接用浏览器和命令行工具如curl。7.1 第一步用户授权请求第三方天气客户端client_id:weather-client想要获取用户信息它会将用户重定向到授权服务器的授权端点http://localhost:8080/oauth/authorize?response_typecodeclient_idweather-clientredirect_urihttp://localhost:8080/login/oauth2/code/weatherscoperead_userinfo在浏览器中访问这个URL你会被重定向到登录页面由我们上面的SecurityConfig提供。使用user/password登录。登录成功后你会看到授权确认页面Spring OAuth2默认提供询问用户是否授权weather-client访问你的read_userinfo信息。点击“Authorize”。7.2 第二步获取授权码授权成功后浏览器会被重定向到我们预先注册的redirect_uri并且URL中会附带一个code参数http://localhost:8080/login/oauth2/code/weather?codeMs3DcU这个code是随机的。这个code就是授权码它有效期很短通常几分钟且只能使用一次。7.3 第三步用授权码换取访问令牌第三方客户端应用必须在自己的服务器后端拿到这个code后向授权服务器的令牌端点发起一个POST请求换取访问令牌。这一步不能在浏览器前端完成因为需要传递client_secret。使用curl命令模拟curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeauthorization_codecodeMs3DcUredirect_urihttp://localhost:8080/login/oauth2/code/weather参数解释-H Authorization: Basic ...这是HTTP Basic认证头用于传递客户端凭证。d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA是weather-client:client-secret的Base64编码。grant_typeauthorization_code声明使用授权码模式。code上一步获取的授权码。redirect_uri必须与申请授权码时使用的redirect_uri完全一致。7.4 第四步收到访问令牌和刷新令牌如果一切正常授权服务器会返回一个JSON响应{ access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...很长的一串JWT..., token_type: bearer, expires_in: 3599, scope: read_userinfo, custom_field: This is my custom data, user_id: user, jti: e2a3b1c0-5f8e-4a2b-9c7d-6e5f4a3b2c1d }注意access_token就是一个JWT字符串。响应里还包含了我们自定义的字段custom_field和user_id。同时由于我们在客户端配置中启用了refresh_token响应中也会包含一个refresh_token。7.5 第五步使用访问令牌调用受保护接口现在第三方客户端就可以用这个access_token去调用资源服务器的/userinfo接口了。curl -X GET \ http://localhost:8080/userinfo \ -H Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...在Header中设置Authorization: Bearer access_token。如果令牌有效且scope正确资源服务器将返回{ username: user, custom_field: This is my custom data, scopes: [read_userinfo], message: This is your protected user info. }至此一个完整的OAuth2.0授权码模式 JWT令牌的流程就跑通了。8. 密码模式与刷新令牌实战8.1 密码模式快速获取令牌对于高度信任的客户端如自家开发的手机App可以使用密码模式。客户端直接收集用户的用户名和密码向令牌端点申请令牌。curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typepasswordusernameuserpasswordpasswordscoperead_userinfo参数变成了grant_typepassword并直接传递username和password。返回的令牌格式与授权码模式相同。重要警告再次强调此模式仅限受信任的第一方客户端使用。将用户密码交给第三方应用是极其危险的行为。8.2 使用刷新令牌获取新的访问令牌访问令牌有效期较短如1小时过期后需要重新获取。为了避免让用户再次登录可以使用刷新令牌。curl -X POST \ http://localhost:8080/oauth/token \ -H Authorization: Basic d2VhdGhlci1jbGllbnQ6Y2xpZW50LXNlY3JldA \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typerefresh_tokenrefresh_tokenyour_refresh_token将grant_type设为refresh_token并附上之前获取的refresh_token。成功后会返回一个新的access_token和新的refresh_token刷新令牌通常也是单次使用的或者有滚动更新策略。9. 常见问题、排查技巧与进阶优化在实际整合中你肯定会遇到各种坑。下面是我踩过的一些坑和解决方案。9.1 常见错误码与排查invalid_client: 客户端认证失败。检查client_id和client_secret是否正确HTTP Basic认证头的格式是否正确Base64(client_id:client_secret)以及client_secret在数据库中是否加密存储比较时是否用了正确的PasswordEncoder。invalid_grant: 授权失败。在授权码模式下检查code是否有效、是否已使用过、是否过期以及redirect_uri是否与申请code时完全一致。在密码模式下检查用户名密码是否正确。invalid_token: 资源服务器报告令牌无效。99%的情况是签名验证失败。确保授权服务器和资源服务器使用的JWT签名密钥signingKey完全一致。如果是RS256非对称加密则要确保资源服务器配置的是授权服务器的公钥。insufficient_scope: 访问资源时权限不足。检查请求的接口所需的scope如SCOPE_read_userinfo与令牌中包含的scope是否匹配。在JwtAccessTokenConverter.enhance方法中确保scope被正确写入JWT。Unauthorized401错误: 可能根本没传Authorization头或者令牌已过期。检查网络请求的Header。9.2 JWT相关的最佳实践与坑密钥管理演示用的对称密钥HS256不安全。生产环境务必使用非对称加密RS256。授权服务器用私钥签名资源服务器用公钥验证。公钥可以公开私钥必须严格保护。令牌失效问题JWT一旦签发在过期前无法主动失效。如果需要实现“登出即失效”可以引入一个短期的令牌黑名单Redis登出时将未过期的令牌IDJWT中的jti字段加入黑名单并设置一个较短的TTL。资源服务器在验证签名后再查一下黑名单。不要存放敏感信息JWT的Payload只是Base64编码任何人都可以解码看到。千万不要把密码、手机号等敏感信息放进去。控制Payload大小JWT会被放在每次请求的Header里太大会增加网络开销。只放必要的用户标识和权限信息。时钟偏移服务器之间可能存在微小的时间差可能导致令牌在“过期时间”之前或之后被误判。可以在验证时允许一个小的时钟偏移容差jjwt库支持setAllowedClockSkewSeconds。9.3 进阶优化方向自定义登录页和授权确认页Spring Security默认的页面很丑。你可以通过实现WebSecurityConfigurerAdapter并配置formLogin().loginPage(“/my-login”)来自定义登录页。授权确认页则需要自定义AuthorizationServerEndpointsConfigurer的pathMapping或实现自己的UserApprovalHandler。数据库存储客户端与用户信息将ClientDetailsService和UserDetailsService的实现连接到你的用户表、客户端表。JdbcClientDetailsService和JdbcUserDetailsManager可以帮你快速实现。令牌增强与自定义Claim就像我们在JwtAccessTokenConverter.enhance里做的那样你可以把更多业务需要的用户信息如部门ID、头像URL放入JWT这样资源服务器就无需查用户库。整合Spring Cloud Gateway在微服务架构中通常会在网关层统一进行JWT验证和鉴权而不是在每个资源服务里都配一遍。可以在Gateway中配置一个全局过滤器来解析和验证JWT并将用户信息传递给下游服务。监控与审计记录令牌的颁发、使用和刷新日志对于安全审计和问题排查非常有帮助。整合OAuth2.0和JWT初看配置繁多但一旦理清“授权服务器”、“资源服务器”、“客户端”这三者的关系以及“授权码”、“访问令牌”、“刷新令牌”的流转过程就会豁然开朗。这套组合为构建安全、可扩展的现代应用提供了坚实的基础设施。
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
