Class TokenIntrospection

java.lang.Object
cloud.opencode.base.oauth2.introspection.TokenIntrospection
public class TokenIntrospection extends Object
Token Introspection Client (RFC 7662) Token 内省客户端（RFC 7662）

Implements the OAuth 2.0 Token Introspection protocol as defined in RFC 7662. Allows resource servers to query the authorization server about the state of an access token and retrieve metadata about it.

实现 RFC 7662 定义的 OAuth 2.0 Token 内省协议。允许资源服务器向授权服务器查询 访问 Token 的状态并获取其元数据信息。

Features | 主要功能:

  • RFC 7662 compliant token introspection - 符合 RFC 7662 的 Token 内省
  • Support for token type hints (access_token, refresh_token) - 支持 Token 类型提示
  • Client authentication via client_id and client_secret - 通过 client_id 和 client_secret 进行客户端认证
  • Automatic JSON response parsing - 自动 JSON 响应解析

Usage Examples | 使用示例:

// Create introspection client
// 创建内省客户端
TokenIntrospection introspection = new TokenIntrospection(
    "https://auth.example.com/introspect",
    "my-client-id",
    "my-client-secret",
    httpClient
);

// Introspect a token
// 内省一个 Token
IntrospectionResult result = introspection.introspect(accessToken);
if (result.active()) {
    System.out.println("Token belongs to: " + result.sub());
}

// Introspect with type hint
// 带类型提示的内省
IntrospectionResult result = introspection.introspect(token, "refresh_token");

Security | 安全性:

  • Thread-safe: Yes (immutable state, delegates to thread-safe HTTP client) - 线程安全: 是（不可变状态，委托给线程安全的 HTTP 客户端）
  • Null-safe: Yes (validates all inputs) - 空值安全: 是（验证所有输入）
  • Requires HTTPS endpoint - 要求 HTTPS 端点
Since:
JDK 25, opencode-base-oauth2 V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • TokenIntrospection

      public TokenIntrospection(String introspectionEndpoint, String clientId, String clientSecret, OAuth2HttpClient httpClient)
      Create a new token introspection client. 创建新的 Token 内省客户端。
      Parameters:
      introspectionEndpoint - the introspection endpoint URL | 内省端点 URL
      clientId - the client ID for authentication | 用于认证的客户端 ID
      clientSecret - the client secret for authentication | 用于认证的客户端密钥
      httpClient - the HTTP client to use | 要使用的 HTTP 客户端
      Throws:
      NullPointerException - if any argument is null | 如果任何参数为 null 则抛出

  • Method Details

    • introspect

      public IntrospectionResult introspect(String token)
      Introspect a token without a type hint. 不带类型提示地内省一个 Token。
      Parameters:
      token - the token to introspect | 要内省的 Token
      Returns:
      the introspection result | 内省结果
      Throws:
      OAuth2Exception - with INTROSPECTION_FAILED if introspection fails | 如果内省失败则抛出 INTROSPECTION_FAILED
      NullPointerException - if token is null | 如果 token 为 null 则抛出

    • introspect

      public IntrospectionResult introspect(String token, String tokenTypeHint)
      Introspect a token with an optional type hint. 带可选类型提示地内省一个 Token。
      Parameters:
      token - the token to introspect | 要内省的 Token
      tokenTypeHint - optional hint about the token type (e.g., "access_token", "refresh_token") | 可选的 Token 类型提示（例如 "access_token"、"refresh_token"）
      Returns:
      the introspection result | 内省结果
      Throws:
      OAuth2Exception - with INTROSPECTION_FAILED if introspection fails | 如果内省失败则抛出 INTROSPECTION_FAILED
      NullPointerException - if token is null | 如果 token 为 null 则抛出