AWS Amplify 中实现 AppSync Events 的 SSR 认证方案解析

背景介绍

在基于 AWS Amplify 构建的 React/Next.js 应用中，开发者经常需要处理两种不同的认证场景：客户端渲染(CSR)和服务器端渲染(SSR)。特别是在使用 AppSync Events API 时，传统的客户端认证方式与 SSR 认证模式存在兼容性问题。

核心挑战

AppSync Events API 基于 WebSocket 协议，通常需要在客户端直接建立连接。当应用采用 SSR 认证（使用 HTTP-only cookie）时，由于浏览器安全限制，客户端 JavaScript 无法直接访问这些 cookie，导致无法直接在客户端完成认证流程。

解决方案架构

经过社区讨论和技术验证，我们总结出一套可行的解决方案架构：

1. 服务器端 Token 获取：创建一个安全的 API 端点，专门用于获取当前会话的访问令牌
2. 客户端 Token 注入：通过 Amplify 的自定义 tokenProvider 机制，将服务器获取的令牌注入到 AppSync Events 客户端

实现细节

服务器端实现

在 Next.js 应用中创建一个受保护的 API 路由，用于安全地获取当前用户的访问令牌：

// API路由实现
import { NextResponse } from "next/server"
import { cookies } from "next/headers"
import { fetchAuthSession } from "aws-amplify/auth/server"

export async function GET() {
  try {
    const session = await runWithAmplifyServerContext({
      nextServerContext: { cookies },
      operation: (contextSpec) => fetchAuthSession(contextSpec),
    })

    if (!session.tokens?.accessToken) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
    }

    return NextResponse.json({
      accessToken: session.tokens.accessToken.toString(),
    })
  } catch (error) {
    console.error("获取令牌失败:", error)
    return NextResponse.json({ error: "服务器错误" }, { status: 500 })
  }
}

客户端配置

在需要使用 AppSync Events 的客户端组件中，配置 Amplify 使用自定义令牌提供器：

// 客户端配置
Amplify.configure(
  {
    API: {
      Events: {
        endpoint: `https://events.example.com/event`,
        region: 'us-east-1',
        defaultAuthMode: "userPool",
      },
    },
  },
  {
    Auth: {
      tokenProvider: {
        getTokens: async () => {
          const res = await fetch("/api/cognito-token")
          const { accessToken } = await res.json()
          return {
            accessToken: decodeJWT(accessToken),
          }
        },
      },
    },
  },
)

安全注意事项

1. API 端点保护：确保令牌获取端点的访问受到严格限制，仅允许认证用户访问
2. 令牌有效期：考虑令牌刷新机制，避免使用过期令牌
3. 错误处理：实现完善的错误处理流程，包括令牌获取失败时的降级方案

方案优势

1. 保持 SSR 优势：继续使用 HTTP-only cookie 的安全特性
2. 兼容现有架构：无需改变现有的认证流程
3. 灵活性：可根据业务需求调整令牌获取逻辑

适用场景

该方案特别适合以下应用场景：

• 主要使用 SSR 但需要部分客户端实时功能的应用
• 对安全性要求较高，必须使用 HTTP-only cookie 的项目
• 已经基于 Amplify 构建但需要扩展实时功能的应用

总结

通过这种服务器端令牌获取+客户端注入的方案，开发者可以在保持 SSR 认证优势的同时，实现 AppSync Events API 的集成。这种架构既满足了安全需求，又提供了必要的实时功能支持，是混合渲染应用的理想选择。