AWS Cognito邮件MFA登录流程疑问及SES发送异常排查

问题描述 #

我已配置AWS Cognito用户池，将邮件设为MFA选项，完成了SES的配置、邮箱注册验证及与Cognito的关联以发送验证码。我的应用基于FastAPI开发，使用boto3的Cognito客户端进行操作，未采用托管UI，而是自定义登录页面。

根据我的理解，当MFA启用且邮件配置完成后，用户登录时应触发EMAIL_OTP挑战，通过邮件发送验证码，用户输入验证码后调用respond_to_auth_challenge完成验证。但我存在两个疑问：

1. 在MFA登录场景下，Cognito如何发送验证码？新用户注册流程中我使用admin_create_user发送临时密码，但admin_initiate_auth中没有类似选项。
2. SES显示邮件已发送，但我未收到任何邮件。

附上部分登录代码片段：

cognito = utils.get_cognito_client()
secret_hash = utils.get_secret_hash(payload.username)
try:
    response = cognito.admin_initiate_auth(
        AuthFlow="ADMIN_NO_SRP_AUTH",
        UserPoolId=settings.default_cognito_user_pool_id,
        ClientId=settings.default_cognito_client_id,
        ClientMetadata={"IpAddress": payload.ip_address},
        AuthParameters={
            "USERNAME": payload.username,
            "PASSWORD": payload.password,
            "SECRET_HASH": secret_hash,
        },
    )
    if response.get("ChallengeName") == "NEW_PASSWORD_REQUIRED":
        # Return session ID for resetting the password
        return {
            "message": "New password required.",
            "session_id": response["Session"],
        }
    if response.get("ChallengeName") == "EMAIL_OTP":
        # Return session ID for validating code
        return {
            "message": f"One Time Password sent to {payload.username}",
            "session_id": response["Session"]
        }

问题解答 #

1. Cognito邮件MFA验证码的发送逻辑 #

当用户通过admin_initiate_auth（ADMIN_NO_SRP_AUTH流程）完成账号密码验证后，若满足以下两个条件，Cognito会自动触发邮件验证码发送，无需在admin_initiate_auth中额外配置发送选项：

• 用户池全局已启用邮件MFA
• 该用户个人已开启邮件MFA（可通过用户自主操作开启，或调用admin_set_user_mfa_preference接口强制开启）

你的代码中，当response返回ChallengeName="EMAIL_OTP"时，说明Cognito已经完成了验证码的发送操作。此时只需要引导用户输入验证码，再调用respond_to_auth_challenge接口，传入以下参数即可完成验证：

• Session：从admin_initiate_auth的响应中获取的会话ID
• ChallengeName="EMAIL_OTP"
• ChallengeResponses：包含USERNAME（用户账号）和EMAIL_OTP_CODE（用户输入的验证码）

如果用户未开启个人MFA，即使用户池全局启用了MFA，登录时也不会触发EMAIL_OTP挑战。可调用admin_get_user接口，检查用户的UserMFASettingList字段，确认是否已开启邮件MFA。

2. SES显示发送成功但未收到邮件的排查方向 #

• 检查垃圾邮件文件夹：很多情况下，验证码邮件会被收件箱标记为垃圾邮件，优先查看垃圾邮件目录
• 查看SES投递详情：在SES控制台的「邮件队列」中查看具体投递状态，确认是否存在服务商拦截的情况，可更换公共邮箱（如Gmail、Outlook）测试
• 确认Cognito邮件模板：检查用户池的「邮件模板」中，MFA验证邮件的模板是否正确配置，是否包含验证码变量{####}，且模板未被标记为违规内容
• 检查SES沙箱模式：若SES处于沙箱模式，仅能发送邮件到已验证的收件邮箱，需确认测试邮箱已完成SES验证，或申请移出沙箱模式
• 验证权限配置：确认Cognito用户池关联的SES身份拥有发送权限，且用户池对应的IAM角色包含ses:SendEmail或ses:SendRawEmail权限

内容的提问来源于stack exchange，提问作者Eternal Doubter