基于JWT的认证方案

[wjwang00]

在openApi和portal接口请求统一的需求下，将portal改造为通过token的方式实现认证。
经讨论，拟选用如下方案：

完全自定义登录接口，通过 Controller 实现认证与 JWT 生成。

接口

1. 登录接口

• url：/api/login
• method：POST
• content-type：application/json
• request body：

{
"username": "string",  // 用户名
"password": "string"   // 密码
}

• 成功响应：

HTTP/1.1 200 OK
Set-Cookie: refresh_token=eyJhb...; HttpOnly; SameSite=Strict; Path=/; Max-Age=xxxx
Content-Type: application/json

{
  "accessToken": "string"
}

• 失败响应：

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "status": 401,
 "message": "用户名或密码错误",
 "timestamp": "2025-07-14T12:34:56.789",
 "exception": "com.ctrip.framework.apollo.common.exception.AuthException"
}

2. 刷新token接口

• url：/api/refresh-token

• method：POST

• content-type：application/json

• 成功响应：

HTTP/1.1 200 OK
Set-Cookie: refresh_token=NEW_eyJhb...; HttpOnly; SameSite=Strict; Path=/; Max-Age=xxx...
Content-Type: application/json

{
  "accessToken": "string"
}

• 失败响应：

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "status": 401,
 "message": "刷新令牌无效或已过期",
 "timestamp": "2025-07-14T12:34:56.789",
 "exception": "org.springframework.security.access.AuthException"
}

3. 登出接口

• url：/api/logout
• method：POST
• content-type：application/json
• 需携带有效的访问令牌（Authorization头）
• 需携带刷新令牌（Cookie）
• 成功响应：

HTTP/1.1 200 OK
Set-Cookie: refresh_token=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0
Content-Type: application/json

{}

• 失败响应：

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
 "status": 401,
 "message": "令牌无效或已过期",
 "timestamp": "2025-07-14T12:34:56.789",
 "exception": "org.springframework.security.access.AuthException"
}

流程图

1. 登录

2. 校验流程

3. 刷新token

自定义登录接口 + JWT

1. 禁用默认 formLogin，配置 WebSecurity

在auth 和 ldap 认证模式下要禁用默认的 formLogin，通过自定义登录接口登录

        @Override
 protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .cors()
            .and()
            .authorizeRequests()
                .antMatchers("/api/login").permitAll() // 登录接口公开
                .antMatchers(BY_PASS_URLS).permitAll()
                .anyRequest().authenticated()
            .and()
            .addFilterBefore(new JwtAuthenticationFilter(JwtTokenUtil, userDetailsService), 
                            SecurityContextPersistenceFilter.class);
    }

oicd 略有差异，​​OIDC完成身份验证后，生成内部JWT用于业务接口鉴权​​。这可以在默认OAuth2Login流程中​​扩展实现​​，无需完全重写登录流程。主要是在OIDC认证成功后，​​拦截用户信息并生成JWT​​返回

    // 3. 配置oauth2Login使用自定义处理器
    http.oauth2Login(configure -> {
        configure.clientRegistrationRepository(
            new ExcludeClientCredentialsClientRegistrationRepository(
                this.clientRegistrationRepository
            )
        );
        // 使用自定义成功处理器
        configure.successHandler(tokenAuthHandler);
    });
    
    // ... [保持其他配置]
    
    // 添加JWT认证过滤器（确保后续请求使用token）
    http.addFilterBefore(jwtAuthenticationFilter(), SecurityContextPersistenceFilter.class);
    

2. 自定义登录接口 Controller

@RestController
@RequestMapping("/api")
public class AuthController {

    @Autowired
    private JwtTokenUtil jwtTokenUtil;

    @Autowired
    private AuthenticationManager authenticationManager;

    @Autowired
    private UserDetailsService userDetailsService;

    @PostMapping("/login")
    public ResponseEntity<?> login(
        @RequestBody LoginRequest authRequest,
        HttpServletResponse response, 
        HttpServletRequest request   
    ) {
        try {
            // 1. 认证用户
            Authentication authentication = authenticationManager.authenticate(
                new UsernamePasswordAuthenticationToken(
                    authRequest.getUsername(), 
                    authRequest.getPassword()
                )
            );
            
            // 2. 生成Token
            UserDetails userDetails = (UserDetails) authentication.getPrincipal();
            String accessToken = jwtTokenUtil.generateAccessToken(userDetails);  // 短时效Token
            String refreshToken = jwtTokenUtil.generateRefreshToken(userDetails);  // 长时效Token
            
            // 3. 设置refreshToken到HttpOnly Cookie
            setRefreshTokenCookie(response, request, refreshToken);
            
            // 4. 返回accessToken（响应体）
            return ResponseEntity.ok(new LoginResponse(accessToken));
        } catch (BadCredentialsException e) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("用户名或密码错误");
        }
    }

    @PostMapping("/refresh-token")
    public ResponseEntity<?> refreshToken(HttpServletRequest request) {
        // 1. 从Cookie中提取refreshToken

        // 2. 验证refreshToken有效性

        // 3. 生成新accessToken
        String username = jwtTokenUtil.getUsernameFromToken(refreshToken);
        UserDetails userDetails = userDetailsService.loadUserByUsername(username);
        String newAccessToken = jwtTokenUtil.generateAccessToken(userDetails);

        // 4. 可选：生成新refreshToken并替换旧Cookie（增强安全性）
        String newRefreshToken = jwtTokenUtil.generateRefreshToken(userDetails);
        setRefreshTokenCookie(request, newRefreshToken);  // 更新Cookie

        return ResponseEntity.ok(new LoginResponse(newAccessToken));
    }

    // 设置refreshToken Cookie HTTP Only
    private void setRefreshTokenCookie(HttpServletResponse response,HttpServletRequest request,String refreshToken) {
    }
}

    // 清除refreshToken Cookie，前端删除accessToken
        @PostMapping("/logout")
        public ResponseEntity<?> logout(HttpServletResponse response) {
            // 清除refreshToken Cookie（设置过期时间为0）
        }
    

3. 实现 JWT 工具类

处理 JWT 生成、验证和解析：

@Component
public class JwtTokenUtil {
    private final SecretKey secretKey;
    private final long expiration;

    public JwtTokenUtil(JwtConfig config) {
        this.secretKey = Keys.hmacShaKeyFor(config.getSecret().getBytes(StandardCharsets.UTF_8));
        this.expiration = config.getExpiration();
    }

    // 生成令牌
    public String generateToken(UserDetails user) {
                    //todo
    }

    // 验证令牌有效性
    public boolean validateToken(String token) {
                    //todo
    }

    // 从令牌获取用户名
    public String getUsernameFromToken(String token) {
              //todo     
    }

    
    // 生成refreshToken（长时效）
    public String generateRefreshToken(UserDetails user) {
                    //todo  
    }


}

4. 实现 JWT 认证过滤器

拦截请求并验证 JWT，设置认证信息到 SecurityContext：

public class JwtAuthenticationFilter extends OncePerRequestFilter {
    private final JwtTokenUtil tokenProvider;
    private final UserDetailsService userDetailsService;

    public JwtAuthenticationFilter(JwtTokenUtil provider, UserDetailsService service) {
        this.tokenProvider = provider;
        this.userDetailsService = service;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain) 
            throws ServletException, IOException {
        // 主要逻辑是：验证请求中带的token，如果有效则从token中提取用户名，然后通过用户名获取用户信息，最后将用户信息设置到SecurityContext中，以便后续的权限校验使用。
        String token = extractToken(req);
        if (token != null && tokenProvider.validateToken(token)) {
            String username = tokenProvider.getUsernameFromToken(token);
            UserDetails user = userDetailsService.loadUserByUsername(username);
            UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(
                    user, null, user.getAuthorities());
            auth.setDetails(new WebAuthenticationDetailsSource().buildDetails(req));
            SecurityContextHolder.getContext().setAuthentication(auth);
        }
       
        chain.doFilter(req, res);
    }

    private String extractToken(HttpServletRequest req) {
        // 从请求中获取token
    }
}

5. UserInfoHolder 和 LogoutHandler

自定义的JwtAuthenticationFilter在请求来解析用户信息后，依旧会调用SecurityContextHolder.getContext().setAuthentication(authentication);，所以UserInfoHolder从 SecurityContextHolder中获取数据，并不影响，无要调整。

LogoutHandler要清除cookie中的长时效token

[wjwang00]

cc @nobodyiam @hezhangjian

[hezhangjian]

Thanks for your work, but I think yaml format interface is better, and I think this interface description is not align to RESTful API design principles.

[spaceluke]

yaml format could be generated by some tools like swagger.

[spaceluke]

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
"code": 401,
"message": "令牌无效或已过期",
"timestamp": "2025-07-14T12:34:56.789",
"exception": "org.springframework.security.access.AuthException"
}

this should not have "code" field neither

[wjwang00]

Thank you for pointing this out. I've confirmed the implementation in GlobalDefaultExceptionHandler - it should indeed be status instead of code.