AWS Amplify JS 身份验证中的 Cookie 域配置问题深度解析

问题背景

在基于 AWS Amplify JS 构建的 Next.js 应用中，开发团队遇到了一个棘手的身份验证问题：部分用户在使用特定浏览器时无法正常登录，系统报错"Unable to get user session following successful sign-in"。经过深入调查，发现问题根源在于 Cookie 的域(domain)配置不一致导致的会话管理异常。

问题现象

应用表现出的主要症状包括：

1. 用户登录后立即出现会话中断异常
2. 页面出现自动刷新循环
3. 仅在特定浏览器(如Chrome)中出现，而Firefox或隐身模式下工作正常
4. 清除全部历史Cookie后问题暂时解决

技术分析

根本原因

问题源于AWS Amplify的两种Cookie设置方式存在不一致：

1. 客户端配置：通过cognitoUserPoolsTokenProvider.setKeyValueStorage显式设置了Cookie的domain为"example.com"
2. 服务端配置：在Next.js的Server Actions或Route Handlers中调用fetchAuthSession时，@aws-amplify/adapter-nextjs会使用默认domain设置Cookie

这种不一致导致系统维护了两套不同domain的认证Cookie。当用户登出时，客户端只能清除显式配置domain的Cookie，而服务端设置的Cookie仍然保留。

问题链

1. 残留Cookie过期，触发token刷新流程
2. 由于domain不匹配，刷新请求失败(400错误)
3. 应用监听到tokenRefresh_failure事件，执行登出操作
4. 登出操作只能清除部分Cookie，残留Cookie仍然存在
5. 用户再次登录时，系统检测到不一致的会话状态，抛出"UnexpectedSignInInterruptionException"

解决方案

方案一：统一Cookie域配置

最彻底的解决方案是确保整个应用中Cookie的domain配置完全一致：

// 客户端配置
cognitoUserPoolsTokenProvider.setKeyValueStorage(
  new CookieStorage({
    domain: "example.com", // 明确指定与后端一致的domain
    secure: true,
    path: '/',
    sameSite: 'lax',
    expires: 30,
  })
);

同时需要确保服务端不会使用默认domain设置Cookie。

方案二：避免服务端token刷新

修改应用架构，确保fetchAuthSession只在客户端执行，不在Server Actions或Route Handlers中触发token刷新操作。这种方式更符合JWT的最佳实践。

方案三：增强登出处理

实现自定义的登出逻辑，主动清理可能存在的各种domain的Cookie：

function enhancedSignOut() {
  // 清除当前domain的Cookie
  await signOut();
  
  // 清除其他可能domain的Cookie
  document.cookie = `Amplify.${key}=; domain=.example.com; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
  document.cookie = `Amplify.${key}=; domain=example.com; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
}

最佳实践建议

1. 环境一致性：确保开发、测试和生产环境使用相同的domain配置
2. Cookie监控：实现Cookie检查机制，在开发阶段就能发现不一致问题
3. 错误处理：对tokenRefresh_failure事件实现更精细的处理逻辑
4. 测试策略：在跨浏览器测试中特别关注认证状态的持久性
5. 文档审查：仔细检查所有依赖库的Cookie处理行为，特别是默认配置

经验总结

这个案例展示了分布式会话管理中Cookie配置一致性的重要性。在现代化前端架构中，特别是使用SSR/SSG时，开发者需要注意：

1. 客户端和服务端的认证状态必须同步
2. 第三方库的默认配置可能带来隐藏问题
3. 浏览器对Cookie的处理存在差异，需要全面测试
4. 完善的错误处理和日志记录对排查认证问题至关重要

通过这个问题的解决过程，团队不仅修复了具体bug，更建立了更健壮的身份验证架构，为后续开发积累了宝贵经验。