4. 令牌校验端点设计：/introspect 与 /userinfo 的区别与适用场景

在 OAuth 2.0 与 OpenID Connect (OIDC) 的混合架构中，资源服务器（Resource Server, RS）通常需要两种不同的令牌校验能力：令牌的活性与合法性校验，以及令牌持有者的身份与属性获取。这两个职责分别由 /introspect 和 /userinfo 端点承担。混淆它们的设计意图，会导致安全漏洞或性能灾难。

4.1 核心职责对比

4.2 适用场景矩阵

根据不同的架构角色与安全需求，选择正确的端点：

• API 网关 / 资源服务器（无状态校验）：使用 /introspect。网关在每次请求到达后端服务前，调用 introspection 端点确认令牌是否 active，并提取 scope 做细粒度权限判断。这是最标准的 OAuth 2.0 资源保护模式。
• 微服务间调用（令牌传播）：使用 /introspect。下游服务收到上游传递的令牌后，应 introspection 而非 userinfo，因为下游不需要用户个人信息，只需要令牌有效性。
• 前端 SPA / 移动端获取用户资料：使用 /userinfo。客户端在登录成功后，通过 access token 调用 userinfo 端点获取用户昵称、头像、邮箱等展示信息。
• 令牌撤销检测（黑名单场景）：必须使用 /introspect。userinfo 端点无法返回 active: false 状态，它只会返回 401 或 403，无法区分“令牌过期”与“令牌被撤销”。
• OIDC 身份认证流程（ID Token 验证）：使用 /userinfo。OIDC 标准要求 RP 在收到 ID Token 后，应调用 userinfo 端点获取用户声明，并与 ID Token 中的 sub 比对，防止令牌伪造。

4.3 端点调用流程对比（SVG 架构图）

4.4 工程落地：缓存与异步刷新策略差异

由于两个端点的调用频率与安全要求不同，缓存策略也应差异化设计：

4.5 代码示例：Go 语言端点调用实现

以下示例展示资源服务器如何安全调用 /introspect 端点，并区分与 /userinfo 的调用方式：

// introspection 调用（资源服务器侧）
func introspectToken(ctx context.Context, token string) (*IntrospectResult, error) {
    // 使用客户端凭证认证（client_secret_basic）
    auth := base64.StdEncoding.EncodeToString([]byte(clientID + ":" + clientSecret))
    reqBody := url.Values{"token": {token}, "token_type_hint": {"access_token"}}
    
    req, _ := http.NewRequestWithContext(ctx, "POST", asIntrospectURL, 
        strings.NewReader(reqBody.Encode()))
    req.Header.Set("Authorization", "Basic "+auth)
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
    
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("introspect call failed: %w", err)
    }
    defer resp.Body.Close()
    
    var result IntrospectResult
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }
    if !result.Active {
        return nil, ErrTokenInactive
    }
    return &result, nil
}

// userinfo 调用（客户端侧，仅需 Bearer Token）
func fetchUserInfo(ctx context.Context, accessToken string) (*UserInfo, error) {
    req, _ := http.NewRequestWithContext(ctx, "GET", oidcUserInfoURL, nil)
    req.Header.Set("Authorization", "Bearer "+accessToken)
    
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("userinfo call failed: %w", err)
    }
    defer resp.Body.Close()
    
    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("userinfo returned %d", resp.StatusCode)
    }
    
    var info UserInfo
    if err := json.NewDecoder(resp.Body).Decode(&info); err != nil {
        return nil, err
    }
    return &info, nil
}