Node.js后端通过aws-sdk查询AWS Cognito User Pool指定邮箱用户是否存在的方法

无需终端用户凭证即可实现该需求的正规方案和替代方案如下，所有方案均符合AWS官方规范：

方案1：服务端IAM授权调用管理端接口（推荐正规方案） #

• 原理：AWS Cognito的管理类API本身支持通过IAM身份授权调用，不需要任何终端用户的访问凭证，只要你的Node.js后端运行环境配置了拥有对应Cognito权限的IAM身份即可，支持EC2实例角色、ECS任务角色、Lambda执行角色、本地开发IAM用户等多种身份形式。
• 权限配置：给你的后端运行身份添加如下IAM权限，将Resource替换为你自己的User Pool ARN即可：

{
  "Effect": "Allow",
  "Action": ["cognito-idp:ListUsers"],
  "Resource": "arn:aws:cognito-idp:<AWS区域>:<AWS账号ID>:userpool/<用户池ID>"
}

• Node.js（aws-sdk v3）示例代码：

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

// 客户端会自动读取运行环境的IAM身份凭证，无需手动配置密钥
const cognitoClient = new CognitoIdentityProviderClient({ region: "你的AWS区域" });

async function checkEmailRegistered(email, userPoolId) {
  const listCommand = new ListUsersCommand({
    UserPoolId: userPoolId,
    Filter: `email = "${email}"`,
    Limit: 1
  });
  const res = await cognitoClient.send(listCommand);
  return res.Users.length > 0;
}

// 调用示例
checkEmailRegistered("test@example.com", "你的用户池ID")
  .then(isExists => console.log("邮箱是否已注册：", isExists));

• 优势：无副作用、权限可控、查询效率高，适合所有可控后端服务场景。

方案2：利用公开注册接口返回值判断（轻量替代方案） #

• 原理：Cognito的公开SignUp接口不需要提前获取用户凭证，调用时如果传入的邮箱（需提前开启用户池邮箱作为登录别名/用户名的配置）已经被注册，会直接返回UsernameExistsException错误，可通过捕获该错误判断邮箱是否存在。
• 适用场景：不想给后端配置IAM权限、或者需要做轻量前置校验的场景，注意必须做好接口限流、验证码等防护，避免被恶意枚举用户。
• Node.js（aws-sdk v3）示例代码：

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

const cognitoClient = new CognitoIdentityProviderClient({ region: "你的AWS区域" });

async function checkEmailRegistered(email, appClientId) {
  try {
    const signUpCommand = new SignUpCommand({
      ClientId: appClientId, // 你的Cognito应用客户端ID，不需要配置客户端密钥
      Username: email,
      Password: "TempPass123!@#" // 随便生成的符合复杂度要求的临时密码，不会真的创建用户
    });
    await cognitoClient.send(signUpCommand);
    // 走到此处说明邮箱不存在，存在会直接抛出对应错误
    return false;
  } catch (err) {
    if (err.name === "UsernameExistsException") return true;
    // 其他错误如密码不符合规则、客户端ID无效等按需处理
    throw err;
  }
}

• 注意：该方案不会真的创建用户，邮箱存在的校验会在用户创建流程前执行，直接抛出错误终止流程。

通用注意事项 #

• 两种方案都需要提前确认你的Cognito User Pool已开启邮箱属性唯一校验，避免出现同一个邮箱对应多个用户的情况导致判断不准确。

内容的提问来源于stack exchange，提问作者Ioannis Panagopoulos