AWS Amplify JS 中社交登录 Cookie 设置问题的解决方案

问题背景

在使用 AWS Amplify JS 进行社交登录（如 Google 登录）时，开发者可能会遇到 Cookie 无法正确设置的问题。这个问题通常表现为：

1. 本地开发环境（localhost）工作正常，但生产环境 Cookie 无法创建
2. 使用电子邮件/密码登录时 Cookie 设置正常，但社交登录时失败
3. 登录流程看似完成，但无法获取当前用户信息

核心问题分析

经过深入分析，这个问题通常由以下几个因素导致：

1. Cookie 配置不完整：特别是缺少必要的 path 参数
2. 多页面应用的特殊性：与单页面应用不同，多页面应用需要额外处理
3. 域名配置问题：生产环境与开发环境的域名配置差异

解决方案

1. 完善 Cookie 配置

正确的 Cookie 配置应该包含以下关键参数：

const isLocalhost = window.location.hostname === "localhost";

export const cookieConfiguration = { 
    secure: !isLocalhost, // 生产环境必须为 true
    sameSite: isLocalhost ? 'lax' : 'none', // 生产环境建议 'none'
    path: "/", // 必须设置为根路径
    domain: isLocalhost ? 'localhost' : 'yourdomain.com' // 生产环境域名
};

特别注意：

• path: "/" 是必须的，否则 Cookie 可能只在特定路径下可用
• secure 在生产环境必须为 true（HTTPS）
• sameSite 在生产环境建议设为 'none' 以支持跨站请求

2. 多页面应用的特殊处理

对于使用 React Router 等多页面应用，需要特别注意：

1. 初始化配置：确保在应用入口正确配置 Amplify

import { Amplify } from 'aws-amplify';
import { awsconfig } from 'aws-exports';
import { CookieStorage } from 'aws-amplify/utils';
import { cognitoUserPoolsTokenProvider } from '@aws-amplify/auth/cognito';

Amplify.configure(awsconfig);
cognitoUserPoolsTokenProvider.setKeyValueStorage(new CookieStorage(cookieConfiguration));

2. 社交登录回调处理：需要在回调页面（如 /auth/session/external/signin）显式处理 OAuth 响应

import { useEffect } from 'react';
import { Hub } from 'aws-amplify/utils';
import { useNavigate } from 'react-router-dom';
import { getCurrentUser } from 'aws-amplify/auth';

const SocialCallbackHandler = () => {
  const navigate = useNavigate();

  useEffect(() => {
    const handleOAuthResponse = async () => {
      try {
        const { username } = await getCurrentUser();
        if(username) {
          navigate('/dashboard');
        } else {
          navigate('/login');
        }
      } catch (error) {
        console.error('OAuth 流程失败', error);
        navigate('/login');
      }
    };
    
    handleOAuthResponse();
  }, [navigate]);

  return null;
};

export default SocialCallbackHandler;

3. 生产环境检查清单

1. 域名一致性：确保 aws-exports.js 中的 redirectSignIn 和 redirectSignOut 使用完整的生产域名
2. HTTPS 强制：生产环境必须使用 HTTPS
3. Cognito 应用客户端设置：检查 Cognito 用户池中的应用客户端设置，确保允许的回调 URL 包含生产域名
4. Cookie 域设置：确保 Cookie 的 domain 参数正确设置为生产域名（不带协议和路径）

常见问题排查

1. Cookie 未创建：

   • 检查网络请求，确认是否有向 Cognito 的 /oauth2/token 端点发送请求
   • 验证响应中是否包含 Set-Cookie 头部

2. 登录流程卡住：

   • 确保回调页面正确处理了 OAuth 响应
   • 检查是否有未捕获的异常

3. 跨域问题：

   • 确认 sameSite 和 secure 设置正确
   • 检查浏览器控制台是否有安全警告

最佳实践建议

1. 环境区分：为开发、测试和生产环境使用不同的 Cognito 应用客户端
2. 错误处理：实现全面的错误处理和用户反馈
3. 日志记录：在关键步骤添加日志记录，便于问题排查
4. 测试策略：
   • 在本地测试时使用生产环境配置
   • 使用浏览器隐身模式测试，避免缓存影响

通过以上措施，可以解决 AWS Amplify JS 中社交登录的 Cookie 设置问题，确保用户认证流程在生产环境正常工作。