AWS Amplify Gen2 中 SignInWithApple 集成时邮箱属性缺失问题解析

问题背景

在使用 AWS Amplify Gen2 进行身份验证集成时，开发者可能会遇到一个特定问题：当配置 Apple 作为外部身份提供商（SignInWithApple）时，即使用户池要求邮箱属性为必填项，Apple 登录后用户的邮箱信息却未能正确存入 Cognito 用户池。这会导致首次登录成功后，用户登出后无法再次登录的严重问题。

问题本质分析

这个问题的根源在于 Apple 登录服务的隐私保护机制与 Cognito 用户池配置要求之间的不匹配：

1. Apple 的隐私邮箱机制：Apple 允许用户选择隐藏真实邮箱地址，此时会提供一个以 privaterelay.appleid.com 为域名的代理邮箱地址。但某些情况下，这个代理邮箱可能不会自动映射到 Cognito 的用户属性中。

2. Cognito 的必填属性要求：当用户池配置为要求邮箱属性时，所有用户记录必须包含有效的邮箱地址。如果外部提供商未能提供这一属性，就会导致后续登录失败。

3. 与 Google 登录的对比：Google 登录通常会明确返回用户邮箱，因此不会出现此问题，这使得问题在 Apple 登录时更为突出。

解决方案

方案一：调整用户池配置（推荐）

最直接的解决方案是重新配置 Cognito 用户池，取消邮箱属性的必填要求：

1. 创建一个新的用户池，确保不将邮箱设为必填属性
2. 在 Amplify 配置中明确指定使用用户名而非邮箱作为登录标识
3. 这种方案兼容所有外部身份提供商，包括 Apple

方案二：使用 Lambda 触发器自动填充占位邮箱

如果必须保留邮箱必填要求，可以通过 Cognito 的 Post Confirmation Lambda 触发器自动添加占位邮箱：

import { CognitoIdentityProviderClient, AdminUpdateUserAttributesCommand } from "@aws-sdk/client-cognito-identity-provider";

export const handler = async (event) => {
  if (event.triggerSource === "PostConfirmation_ConfirmSignUp" && 
      event.userName.startsWith('signinwithapple_')) {
    
    const identities = JSON.parse(event.request.userAttributes.identities);
    const appleIdentity = identities.find(id => id.providerName === "SignInWithApple");
    
    if (appleIdentity && !event.request.userAttributes.email) {
      const appleSubId = appleIdentity.userId;
      const placeholderEmail = `apple_${appleSubId}@apple-placeholder.com`;
      
      const client = new CognitoIdentityProviderClient({ region: event.region });
      
      const command = new AdminUpdateUserAttributesCommand({
        UserPoolId: event.userPoolId,
        Username: event.userName,
        UserAttributes: [
          { Name: 'email', Value: placeholderEmail },
          { Name: 'email_verified', Value: 'true' }
        ]
      });

      await client.send(command);
    }
  }
  return event;
};

方案三：利用 Apple 提供的私有中继邮箱

最新发现表明，Apple 实际上会提供 privaterelay.appleid.com 域名的代理邮箱地址。开发者可以检查是否已自动使用这一地址，而无需额外处理。

最佳实践建议

1. 前期规划：在项目初期就确定身份验证策略，如果必须支持 Apple 登录，避免将邮箱设为必填属性。

2. 用户通知：当使用占位邮箱方案时，应在 UI 中明确告知用户这一情况，避免混淆。

3. 测试验证：对所有外部身份提供商进行完整的登录-登出-再登录流程测试，确保没有隐藏问题。

4. 监控机制：建立对身份验证失败的监控，及时发现并处理类似问题。

总结

AWS Amplify 与 Apple 登录集成时的邮箱属性问题，本质上是不同平台隐私策略差异导致的。开发者需要根据自身应用需求选择合适的解决方案，要么调整用户池配置以适应 Apple 的隐私策略，要么通过技术手段确保必填属性的完整性。理解这些底层机制有助于构建更健壮的身份验证系统。