AWS Amplify 中 Cognito 用户池 Email MFA 认证问题解析

问题背景

在使用 AWS Amplify 进行用户认证时，开发者可能会遇到 Cognito 用户池的 Email MFA（多因素认证）功能无法正常工作的问题。具体表现为当启用 Email MFA 后，用户认证过程中会出现 Cannot read properties of undefined (reading 'NewDeviceMetadata') 的错误，尽管用户确实能够收到包含验证码的邮件。

技术分析

核心问题

这个问题的根本原因在于使用了不兼容的 SDK 版本。开发者错误地使用了 amazon-cognito-identity-js 这个旧版 SDK（版本 6.3.12），而该版本存在以下限制：

1. 不支持 Amplify JS v6 版本
2. 完全不支持 Email MFA 功能
3. 在处理 MFA 认证流程时存在兼容性问题

错误机制

当 Cognito 用户池配置了 Email MFA 后，认证流程会分为两个阶段：

1. 第一阶段：验证用户名和密码
2. 第二阶段：通过邮件发送的验证码进行二次验证

旧版 SDK 无法正确处理这个流程，导致在 authenticateUserInternal 方法中尝试访问 NewDeviceMetadata 属性时抛出异常，因为该属性在 Email MFA 场景下并不存在。

解决方案

正确使用 AWS Amplify Auth

要解决这个问题，开发者应该：

1. 使用 aws-amplify 主包或 @aws-amplify/auth 模块
2. 遵循官方推荐的认证实现方式

实现示例

以下是使用正确 SDK 实现 Email MFA 认证的示例代码：

import { Auth } from 'aws-amplify';

async function signIn(username: string, password: string) {
  try {
    const user = await Auth.signIn(username, password);
    
    if (user.challengeName === 'SMS_MFA' || user.challengeName === 'EMAIL_OTP') {
      // 处理 MFA 验证
      const code = getCodeFromUserInput(); // 获取用户输入的验证码
      const loggedUser = await Auth.confirmSignIn(
        user,   // 返回的用户对象
        code,   // 验证码
        user.challengeName // MFA 类型
      );
    }
  } catch (error) {
    console.log('error signing in', error);
  }
}

最佳实践建议

1. SDK 选择：始终使用最新版本的 aws-amplify 包，避免直接使用底层 SDK
2. 错误处理：完善认证流程中的错误处理机制，特别是针对不同 MFA 类型的处理
3. 测试策略：在开发环境中充分测试各种 MFA 场景，包括：
   • SMS 验证
   • Email 验证
   • TOTP 验证
4. 配置检查：确保 Cognito 用户池中的 MFA 配置正确，特别是：
   • MFA 强制级别
   • 验证消息模板
   • 邮件发送配置

总结

在 AWS Amplify 生态系统中实现安全的用户认证时，正确选择和使用 SDK 至关重要。通过采用官方推荐的 aws-amplify/auth 模块，开发者可以避免类似 Email MFA 不兼容的问题，同时获得更好的功能支持和更稳定的认证体验。对于需要实现多因素认证的场景，建议开发者仔细阅读官方文档，了解不同 MFA 类型的实现差异和最佳实践。