如何在我的 Cognito 用户池中实现无密码身份验证？

简短描述

Amazon Cognito 支持两种无密码身份验证方法：

• 使用一次性密码 (OTP) 进行无密码登录
• 使用 WebAuthn 通行密钥进行无密码登录

重要事项：

• 如果您需要在用户池中进行多重身份验证 (MFA)，则无法使用无密码身份验证。
• 用户最初进行身份验证后，您最多可以注册 20 个 WebAuthn 密钥。
• 无密码身份验证仅在 ALLOW_USER_AUTH 的基于选择的身份验证 AuthFlow 中可用。
• 您必须拥有 Essentials 或 Plus 功能套餐才能使用基于选择的身份验证。

解决方法

**注意：**如果您在运行 AWS 命令行界面 (AWS CLI) 命令时收到错误，请参阅 AWS CLI 错误故障排除。此外，请确保您使用的是最新版本的 AWS CLI。

OTP 身份验证

启用 OTP 身份验证

完成以下步骤：

1. 打开 Amazon Cognito 控制台。
2. 选择您的用户池。
3. 在 Authentication（身份验证）下，选择 Sign-in（登录）选项卡。
4. 对于 Options for choice-based sign-in（基于选择的登录选项），选择 Edit（编辑）。
5. 选择 Email message one-time password（电子邮件一次性密码）或 SMS message one-time password（短信一次性密码）。
6. 选择 Save changes（保存更改）。
7. 选择 App clients（应用程序客户端），然后打开您的应用程序客户端。或者，创建新的应用程序客户端。
8. 在 App client（应用程序客户端）信息下，选择 Edit（编辑）。
9. 选择 Choice-based sign-in: ALLOW_USER_AUTH（基于选择的登录：ALLOW_USER_AUTH）。
10. 选择 Save Changes（保存更改）。

实现 OTP 身份验证

无密码身份验证仅适用于托管登录。经典的托管用户界面不支持内置的无密码身份验证流程。有关详细信息，请参阅有关使用用户池进行身份验证的注意事项。

要实现 OTP，请完成以下步骤：

1. 设置托管登录。
2. 配置您的前缀域，引导用户在托管登录页面上输入他们的用户名。要使用自定义域，请参阅使用自己的域进行托管登录。

要使用 AWS CLI，请完成以下步骤：

1. 运行 initiate-auth 命令开始身份验证：

   aws cognito-idp initiate-auth --auth-flow USER_AUTH --auth-parameters USERNAME=example_username --client-id example_clientid

   **注意：**请将所有示例值替换为您的值。如果您在前面的命令中加入了 PREFERRED_CHALLENGE，请继续执行步骤 4。

2. 响应包括以下可用挑战：

   {
      "AvailableChallenges": [
         "EMAIL_OTP",
         "SMS_OTP",
         "PASSWORD"
       ],
      "Session": "[Session ID]"
   }

   **注意：**在同一身份验证流程内的所有后续身份验证命令中使用前面响应中的会话 ID。

3. 用户选择首选身份验证方法后，运行 respond-to-auth-challenge 命令以提交他们的选择：

   aws cognito-idp respond-to-auth-challenge --challenge-name SELECT_CHALLENGE --challenge-responses USERNAME=example_username,ANSWER=EMAIL_OTP --client-id example_clientid --session "SESSION_ID_FROM_PREVIOUS_RESPONSE"

   **注意：**如果用户有资格使用所选的挑战方法，则 Amazon Cognito 会向用户的电子邮箱或电话号码发送验证码。

4. 要使用特定的 PREFERRED_CHALLENGE 启动身份验证方法，请运行 initiate-auth 命令：

   aws cognito-idp initiate-auth --auth-flow USER_AUTH --auth-parameters USERNAME=example_username,PREFERRED_CHALLENGE=EMAIL_OTP --client-id example_clientid

   **注意：**如果您更喜欢 SMS 身份验证，请将 EMAIL_OTP 替换为 SMS_OTP。如果用户有资格使用 PREFERRED_CHALLENGE 方法，则 Amazon Cognito 会向用户的电子邮箱或电话号码发送验证码。

5. 运行 respond-to-auth-challenge 命令以返回响应：

   aws cognito-idp admin-respond-to-auth-challenge --challenge-name EMAIL_OTP --challenge-responses USERNAME=example_username,EMAIL_OTP_CODE=OTP_EMAIL --client-id example_clientid --session "SESSION_ID_FROM_PREVIOUS_RESPONSE"

   **注意：**如果您使用短信身份验证，请将 EMAIL_OTP 替换为 SMS_OTP，将 EMAIL_OTP_CODE 替换为 SMS_OTP_CODE。

OTP 验证后，您的用户将收到 Amazon Cognito 生成的 JSON Web 令牌 (JWT)。

WebAuthn 通行密钥身份验证

启用 WebAuthn 通行密钥身份验证

完成以下步骤：

1. 打开 Amazon Cognito 控制台。
2. 选择您的用户池。
3. 在 Authentication（身份验证）下，选择 Sign-in（登录）选项卡。
4. 对于 Options for choice-based sign-in（基于选择的登录选项），选择 Edit（编辑），然后将 Passkey（通行密钥）添加到可用选项中。
5. 选择 Edit passkey（编辑通行密钥），然后配置以下设置：
   将 User verification mode（用户验证模式）设置为 Preferred（首选）或 Required（必填）。
   将 Relying Party ID（信赖方 ID）设置为您的用户池域、自定义域或第三方域。
   **注意：**信赖方 ID 控制可以使用通行密钥进行注册和身份验证的域。
6. 选择 Save changes（保存更改）。
7. 选择 App clients（应用程序客户端），然后打开您的应用程序客户端。或者，创建新的应用程序客户端。
8. 在 App client information（应用程序客户端信息）下，选择 Edit（编辑）。
9. 选择 Choice-based sign-in: ALLOW_USER_AUTH（基于选择的登录：ALLOW_USER_AUTH）。
10. 选择 Save changes（保存更改）。

在托管登录中为用户注册 WebAuthn 通行密钥

完成以下步骤：

1. 在应用程序客户端中设置托管登录。
   **注意：**Amazon Cognito 会自动提示新用户注册时设置通行密钥。

2. 对于尚未注册通行密钥的当前用户，将您的应用程序配置为将其重定向到以下身份验证端点：
   https://auth.example.com/oauth2/authorize/?client_id=1example23456789&response_type=code&scope=email+openid+phone&redirect_uri=https://www.example.com 

3. 将授权码换成令牌。

4. 运行以下 list-web-authn-credentials 命令来检查注册的通行密钥：

   aws cognito-idp list-web-authn-credentials --access-token token-from-above-step

   输出示例：

   {
       "Credentials": [
           {
               "CredentialId": "r8DCexamplecredentialsaWMQ",
               "FriendlyCredentialName": "Chrome on Mac",
               "RelyingPartyId": "<cognito-prefix>.auth.us-east-1.amazoncognito.com",
               "AuthenticatorAttachment": "platform",
               "AuthenticatorTransports": [
                   "internal"
               ],
               "CreatedAt": "2025-06-27T07:41:15.800000+00:00"
           }
       ]
   }

5. 如果前面的命令返回空列表，请将用户重定向到以下托管登录 URL 以开始通行密钥注册过程：
   https://cognito-managed-login-domain/passkeys/add?client_id=example_client_id&redirect_uri=https://www.example.com
   **注意：**确保您在 Cognito 托管登录中具有有效的浏览器会话。此外，添加必填的 OAuth 参数，例如 response_type 和 scope。

在 passkeys/add URL 页面上，用户添加通行密钥。然后，Amazon Cognito 将用户重定向到您在 redirect_uri 参数中指定的应用程序页面。要在托管登录页面上进行后续登录，用户可以使用其注册的通行密钥登录。

相关信息

API 和 SDK 身份验证的授权模型

使用 Amazon Cognito 用户池进行身份验证

身份验证流程