Interface CallbackHandler

All Known Implementing Classes:
CookieCallbackHandler, RedirectToFrontCallbackHandler
public interface CallbackHandler
回调处理器接口

用于处理OAuth 2.0 / OpenID Connect的授权回调

主要功能： 1. 处理HTTP回调请求 2. 提取授权码（code）参数 3. 提取state参数用于CSRF防护 4. 校验回调 state 与发起登录时保存的 state 是否一致（防登录 CSRF）

实现类可以自定义回调处理逻辑，例如： - CookieCallbackHandler：将Token存储到Cookie中 - RedirectToFrontCallbackHandler：重定向到前端页面

Author:
Kerbores(kerbores@riemann.tech)

  • Method Summary

    Modifier and Type
    Method
    Description
    default String
    code(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    从HTTP请求中获取授权码（code）参数
    default String
    cookieSameSite()
    OIDC 会话 Cookie 的 SameSite 策略(M14,默认 Lax)
    void
    handle(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    处理HTTP回调
    static boolean
    isSafeRedirectUrl(String url, String allowedHost)
    校验回跳地址是否安全（防开放重定向）
    default String
    state(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
    从HTTP请求中获取state参数
    default boolean
    validateState(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, boolean checkEnabled)
    校验回调请求中的 state 是否与发起登录时写入 Cookie 的 state 一致（防登录 CSRF）

  • Method Details

    • handle

      void handle(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
      处理HTTP回调

      当OAuth授权服务器回调时，此方法被调用处理授权码等参数

      Parameters:
      request - HTTP请求对象，包含授权码等参数
      response - HTTP响应对象，用于返回处理结果

    • cookieSameSite

      default String cookieSameSite()
      OIDC 会话 Cookie 的 SameSite 策略(M14,默认 Lax)

      删除 cookie 需与写入时使用同一策略;子类可覆写返回配置值

      Returns:
      SameSite 值,如 Lax/Strict/None

    • validateState

      default boolean validateState(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, boolean checkEnabled)
      校验回调请求中的 state 是否与发起登录时写入 Cookie 的 state 一致（防登录 CSRF）

      校验通过后删除 state Cookie（一次性消费），防止重放；校验未启用时直接放行

      Parameters:
      request - HTTP请求对象
      response - HTTP响应对象
      checkEnabled - 是否启用校验（配置开关）
      Returns:
      true 表示校验通过（或未启用）；false 表示校验失败

    • isSafeRedirectUrl

      static boolean isSafeRedirectUrl(String url, String allowedHost)
      校验回跳地址是否安全（防开放重定向）

      规则：空/非法 URI 拒绝；http/https 且 host 必须与成功回调地址同源（allowedHost）才放行； 相对路径（/foo）站内安全放行；scheme-relative（//evil.com）拒绝；javascript:/data: 等协议拒绝

      Parameters:
      url - 待校验的回跳地址（可为 null）
      allowedHost - 允许回跳的主机名（来自配置的成功回调地址 handlerSuccessPage），可为 null（null 时仅放行相对路径）
      Returns:
      true 表示安全

    • code

      default String code(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
      从HTTP请求中获取授权码（code）参数

      如果code参数为空或未提供，则在响应中设置BAD_REQUEST状态码，并记录调试信息

      Parameters:
      request - HTTP请求对象
      response - HTTP响应对象
      Returns:
      授权码参数值，如果为空则返回空字符串

    • state

      default String state(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response)
      从HTTP请求中获取state参数

      state参数用于CSRF防护，验证请求的合法性 如果state参数为空，则在响应中设置BAD_REQUEST状态码

      Parameters:
      request - HTTP请求对象
      response - HTTP响应对象
      Returns:
      state参数值，如果为空则返回空字符串