AWS Amplify Gen2 中 SignInWithApple 的邮箱属性处理问题解析

问题背景

在 AWS Amplify Gen2 项目中，当开发者配置使用 Apple 作为外部身份提供商时，可能会遇到一个棘手的问题：即使用户选择了共享邮箱，Cognito 用户池中也不会存储邮箱属性。这个问题在使用电子邮件作为主要登录方式的用户池中尤为突出，因为当用户首次登录后退出，将无法再次登录。

问题本质

这个问题源于 Apple 的隐私保护机制与 Cognito 用户池配置之间的不匹配：

1. Apple 的隐私邮箱机制：当用户选择"隐藏我的邮箱"时，Apple 会提供一个私有中继邮箱(通常以 privaterelay.appleid.com 结尾)，而不是真实邮箱。

2. Cognito 的必填属性要求：如果用户池配置为要求邮箱属性，而 Apple 没有提供真实邮箱，就会导致后续登录失败。

3. 首次登录成功的原因：首次登录时系统会创建用户记录，但由于缺少必填的邮箱属性，后续登录验证会失败。

解决方案比较

开发者可以考虑以下几种解决方案：

方案一：修改用户池配置

1. 创建新用户池：新建一个不要求邮箱属性的用户池

   • 优点：从根本上解决问题
   • 缺点：需要迁移现有用户数据

2. 改用手机号验证：

   • 优点：符合 Apple 的隐私要求
   • 缺点：可能影响用户体验

方案二：使用 Lambda 触发器

通过 Cognito 的 PostConfirmation 触发器自动添加占位邮箱：

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;
};

• 优点：保持现有用户池配置
• 缺点：需要额外维护 Lambda 函数

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

最新发现 Apple 会自动提供 privaterelay.appleid.com 的占位邮箱：

• 优点：无需额外配置
• 缺点：邮箱格式固定，可能影响业务逻辑

最佳实践建议

1. 评估业务需求：如果邮箱对业务非关键，考虑取消必填要求

2. 多因素验证：结合其他验证方式提高安全性

3. 用户引导：在 UI 中明确提示 Apple 用户关于邮箱隐私的选项

4. 测试策略：全面测试各种 Apple 登录场景（共享邮箱/隐藏邮箱）

技术实现要点

1. Amplify 配置：确保正确设置 scope 和 attributeMapping

signInWithApple: {
  clientId: secret('SIWA_CLIENT_ID'),
  scopes: ['email'],
  attributeMapping: { email: 'email' }
}

2. 错误处理：捕获并妥善处理 OAuthSignInException

3. 用户池设计：权衡安全需求与用户体验

总结

AWS Amplify 与 Apple 登录的集成需要特别注意邮箱属性的处理。开发者应根据具体业务场景选择合适的解决方案，无论是调整用户池配置、使用 Lambda 触发器还是接受 Apple 的私有中继邮箱。理解各身份提供商的不同行为模式对于构建健壮的身份验证系统至关重要。