AWS Amplify 身份验证中"无法获取用户会话"问题的深度分析与解决方案

问题背景

在使用AWS Amplify进行身份验证时，部分用户会遇到一个棘手的问题：在成功登录后系统抛出"UnexpectedSignInInterruptionException: Unable to get user session following successful sign-in"错误。这个问题具有以下特点：

1. 仅影响部分用户，难以在开发环境中复现
2. 在Chrome浏览器中常见，但在Firefox或隐身模式下工作正常
3. 清除浏览器缓存和Cookie后问题可能暂时解决
4. 问题表现为页面不断自动刷新循环

技术分析

根本原因

经过深入调查，发现问题源于AWS Amplify的Cookie管理机制与Next.js服务器端渲染(SSR)的特殊交互方式。具体表现为：

1. Cookie域不一致问题：当使用@aws-amplify/adapter-nextjs在服务器端设置Cookie时，库会使用默认的domain值，而客户端显式配置的Cookie使用不同的domain值。

2. Token刷新机制冲突：当在Next.js的Server Actions或Route Handlers中执行fetchAuthSession并触发token刷新时，会设置带有不同domain字段的Cookie。

3. Cookie清理不彻底：用户注销时，客户端只能清除匹配当前domain配置的Cookie，而服务器端设置的不同domain的Cookie会残留。

4. 过期Token循环：残留的过期Cookie会持续触发token刷新失败，导致系统进入错误循环状态。

错误表现链

1. 用户打开应用，系统尝试使用过期refresh token获取新token
2. 由于domain不匹配的残留Cookie存在，token刷新失败(400错误)
3. 触发tokenRefresh_failure事件，系统执行注销操作
4. 注销操作只能清除部分Cookie，残留Cookie仍然存在
5. 用户尝试登录，系统再次因残留Cookie导致token刷新失败
6. 最终抛出"无法获取用户会话"错误

解决方案

架构层面优化

1. 避免服务器端token操作：重构应用设计，确保fetchAuthSession不在Server Actions和Route Handlers中调用，仅在客户端执行身份验证相关操作。

2. 统一Cookie域设置：检查并确保所有Cookie操作使用一致的domain配置，避免服务器端和客户端设置不一致。

技术实现方案

1. 自定义Cookie清理：实现专门的Cookie清理函数，在注销时彻底清除所有相关Cookie：

function clearAllAuthCookies() {
  const domains = ['.example.com', 'example.com']; // 所有可能的domain变体
  const cookieNames = ['amplify-auth', 'refresh-token']; // Amplify使用的Cookie名称
  
  domains.forEach(domain => {
    cookieNames.forEach(name => {
      document.cookie = `${name}=; domain=${domain}; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
    });
  });
}

2. 增强错误处理：在tokenRefresh_failure事件处理中添加更精细的错误处理和恢复逻辑：

import { Hub } from 'aws-amplify';

Hub.listen('auth', ({ payload }) => {
  if (payload.event === 'tokenRefresh_failure') {
    if (payload.data?.error?.name === 'NotAuthorizedException') {
      // 特定错误处理
      clearAllAuthCookies();
      // 重定向到登录页
    }
  }
});

3. Cookie配置最佳实践：确保Cookie配置一致且安全：

cognitoUserPoolsTokenProvider.setKeyValueStorage(
  new CookieStorage({
    domain: process.env.NEXT_PUBLIC_AUTH_COOKIE_DOMAIN, // 统一配置
    secure: true,
    path: '/',
    sameSite: 'lax',
    expires: 30, // 合理设置过期时间
  })
);

预防措施

1. 环境一致性检查：在应用初始化时验证Cookie配置是否一致。

2. 监控和日志：增强客户端错误监控，特别是针对身份验证流程的监控。

3. 用户引导：为终端用户提供清晰的Cookie管理指导，特别是当遇到登录问题时如何彻底清除浏览器数据。

总结

AWS Amplify身份验证在与Next.js SSR结合使用时，需要特别注意Cookie管理的一致性问题。通过理解Amplify的底层机制和浏览器Cookie处理特性，可以有效地解决这类棘手的身份验证问题。关键在于确保服务器端和客户端的Cookie操作保持一致，并实现全面的Cookie清理机制。

对于复杂的前端身份验证场景，建议采用防御性编程策略，预先考虑各种边缘情况，并建立完善的错误恢复机制，以提供更稳定的用户体验。