使用AWS Cognito AdminCreateUserCommand创建用户时如何发送邮箱验证邮件？

问题背景 #

使用CDK搭建基础设施、Amplify作为前端框架，通过AdminCreateUserCommand创建用户时，希望发送带验证码的邮箱验证邮件，而非Cognito默认的临时密码邀请邮件。已配置Cognito的autoVerify和userVerification参数但未生效，添加了Custom Message Lambda触发器但未达到预期效果，查阅资料得知管理创建流（AdminCreateUser）默认不支持自助注册流的验证邮件逻辑。

核心原因 #

Cognito的**管理创建流（AdminCreateUser）**与用户自助注册流的行为逻辑完全分离：

• 自助注册流会触发autoVerify和userVerification配置，自动发送验证码验证邮件
• 管理创建流默认发送包含临时密码的邀请邮件，不会触发自动邮箱验证流程，因此你之前的Cognito配置无法生效

解决方案 #

通过调整Lambda触发器和AdminCreateUser参数，完全自定义邮件内容并强制邮箱验证流程：

1. 调整Custom Message Lambda触发器 #

针对CustomMessage_AdminCreateUser事件类型，覆盖默认邀请邮件内容为验证码邮件：

exports.handler = async (event) => {
  // 匹配管理创建用户的事件
  if (event.triggerSource === 'CustomMessage_AdminCreateUser') {
    // 自定义验证码邮件主题和内容
    event.response.emailSubject = '验证你的邮箱';
    event.response.emailMessage = `你好 ${event.request.userAttributes.username}，你的邮箱验证码是：${event.request.codeParameter}`;
  }
  return event;
};

2. 配置Pre Sign-Up Lambda触发器（强制邮箱验证） #

确保管理创建的用户处于邮箱未验证状态，必须完成验证才能登录：

exports.handler = async (event) => {
  // 强制开启邮箱自动验证
  event.response.autoVerifyEmail = true;
  
  // 针对管理创建的用户，显式标记邮箱未验证
  if (event.triggerSource === 'PreSignUp_AdminCreateUser') {
    event.response.userAttributes.email_verified = 'false';
  }
  
  return event;
};

3. 修改AdminCreateUserCommand参数 #

禁用默认邀请邮件发送，移除临时密码参数，显式设置邮箱未验证状态：

const userPoolId = process.env.COGNITO_USER_POOL_ID;
const params = {
  UserPoolId: userPoolId,
  Username: validatedEmail,
  DesiredDeliveryMediums: ['EMAIL'],
  UserAttributes: [
    { Name: 'locale', Value: validatedLocale },
    { Name: 'email', Value: validatedEmail },
    { Name: 'email_verified', Value: 'false' } // 显式标记未验证
  ],
  ClientMetadata: { appName: process.env.APP_NAME || 'myApp' },
  MessageAction: 'SUPPRESS' // 阻止Cognito发送默认邀请邮件
};

try {
  await cognitoClient.send(new AdminCreateUserCommand(params));
} catch (err) {
  console.error('创建用户失败:', err);
  throw err;
}

4. 前端Amplify处理验证流程 #

用户收到验证码后，前端需完成邮箱验证和密码设置：

import { Auth } from 'aws-amplify';

// 步骤1：验证邮箱验证码
await Auth.confirmSignUp(validatedEmail, verificationCode);

// 步骤2：设置新密码（管理创建的用户无初始密码）
const user = await Auth.signIn(validatedEmail); // 触发新密码设置流程
await Auth.completeNewPassword(user, newPassword);

// 步骤3：正常登录
const loggedInUser = await Auth.signIn(validatedEmail, newPassword);

验证步骤 #

1. 调用AdminCreateUser接口创建用户，检查邮箱是否收到自定义的验证码邮件
2. 前端输入验证码完成验证，设置新密码
3. 使用新密码登录系统，确认登录成功

内容的提问来源于stack exchange，提问作者Camilo-J