3. OAuth2 回调流程解析：授权码交换、访问令牌获取、刷新令牌机制

OAuth2.0 授权码模式（Authorization Code Grant）是 Web 应用中最安全、最常用的授权流程。本章将深入解析回调环节的核心三阶段：授权码交换、访问令牌获取以及刷新令牌机制。理解这一流程是构建可靠中间件链路的基础。

3.1 完整回调流程总览

一次标准的 OAuth2 回调交互涉及三个角色：客户端（Client）、授权服务器（Authorization Server）和资源服务器（Resource Server）。下图展示了从用户授权到最终使用令牌访问资源的完整链路。

3.2 授权码交换（Authorization Code Exchange）

当用户在前端完成授权并同意后，授权服务器会通过回调 URL 将授权码（code）发送给客户端。此时，客户端需要立即使用该授权码向授权服务器的令牌端点（Token Endpoint）发起交换请求。

3.2.1 请求参数规范

授权码交换请求必须包含以下参数，通常以 application/x-www-form-urlencoded 格式 POST 到令牌端点：

3.2.2 Go 实现示例

// 授权码交换请求示例
func exchangeAuthorizationCode(ctx context.Context, code string) (*TokenResponse, error) {
    data := url.Values{
        "grant_type":   {"authorization_code"},
        "code":         {code},
        "redirect_uri": {config.RedirectURI},
        "client_id":    {config.ClientID},
        "client_secret": {config.ClientSecret},
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        config.TokenEndpoint, strings.NewReader(data.Encode()))
    if err != nil {
        return nil, fmt.Errorf("创建令牌请求失败: %w", err)
    }
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("令牌请求执行失败: %w", err)
    }
    defer resp.Body.Close()

    // 解析响应...
}

3.3 访问令牌获取（Access Token Acquisition）

授权服务器验证授权码和客户端凭证无误后，会返回一个 JSON 响应，其中包含访问令牌（access_token）以及其他可选字段。

3.3.1 成功响应结构

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200b3f7a8e9c1d2...",
  "scope": "read write"
}

3.3.2 错误响应处理

当授权码无效、过期或客户端凭证错误时，授权服务器会返回错误响应。中间件必须能够识别并处理这些错误：

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or expired."
}

3.4 刷新令牌机制（Refresh Token Mechanism）

访问令牌通常具有较短的有效期（如 1 小时），而刷新令牌（refresh_token）用于在访问令牌过期后获取新的访问令牌，无需用户重新授权。刷新令牌通常具有更长的有效期（如 30 天），且只能使用一次。

3.4.1 刷新流程

3.4.2 刷新请求参数

刷新令牌请求同样发送到令牌端点，grant_type 改为 refresh_token：

func refreshAccessToken(ctx context.Context, refreshToken string) (*TokenResponse, error) {
    data := url.Values{
        "grant_type":    {"refresh_token"},
        "refresh_token": {refreshToken},
        "client_id":     {config.ClientID},
        "client_secret": {config.ClientSecret},
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        config.TokenEndpoint, strings.NewReader(data.Encode()))
    if err != nil {
        return nil, fmt.Errorf("创建刷新请求失败: %w", err)
    }
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("刷新请求执行失败: %w", err)
    }
    defer resp.Body.Close()

    // 解析并返回新的令牌响应
}

3.4.3 刷新令牌的安全策略

• 一次性使用：每次刷新成功后，旧的 refresh_token 立即失效，服务器返回新的 refresh_token。
• 存储安全：刷新令牌必须存储在服务端安全区域（如加密数据库或专用令牌存储服务），禁止暴露给前端。
• 撤销机制：当用户主动注销或检测到异常行为时，中间件应调用授权服务器的令牌撤销端点，使刷新令牌立即失效。
• 过期处理：如果刷新令牌也过期，中间件应清除所有令牌状态，引导用户重新进行完整的 OAuth2 授权流程。

3.5 中间件集成要点

在 Go 中间件中实现 OAuth2 回调处理时，建议遵循以下架构原则：

通过精确控制授权码交换、访问令牌获取和刷新令牌机制，中间件能够为用户提供无缝的认证体验，同时保持高安全标准。下一阶段将深入探讨令牌验证与缓存策略，进一步提升系统性能与可靠性。