View a markdown version of this page

TOTP 软件令牌 MFA - Amazon Cognito
为用户配置 TOTP MFA配置您的 AWS WAF 用于管理登录的 Web ACL TOTP MFA

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

TOTP 软件令牌 MFA

当您在用户池中设置了 TOTP 软件令牌 MFA 时，您的用户通过用户名和密码登录，然后使用 TOTP 完成身份验证。用户设置并验证用户名和密码后，就可以为 MFA 激活 TOTP 软件令牌。如果应用程序使用 Amazon Cognito 托管登录来登录用户，则用户提交用户名和密码，然后在额外的登录页面上提交 TOTP 密码。

您可以在 Amazon Cognito 控制台中为用户池激活 TOTP MFA，也可以使用 Amazon Cognito API 操作来激活。在用户池级别，您可以致电SetUserPoolMfaConfig配置 MFA 并启用 TOTP MFA。

注意

如果您没有为用户池激活 TOTP 软件令牌 MFA，则 Amazon Cognito 无法使用此令牌进行关联或验证用户。在这种情况下，用户会收到 SoftwareTokenMFANotFoundException 异常，并带有说明 Software Token MFA has not been enabled by the userPool。如果您稍后为用户池停用了软件令牌 MFA，则以前已关联并验证 TOTP 令牌的用户可以继续将其用于 MFA。

为用户配置 TOTP 是一个多步骤过程，在此过程中，用户将收到一个秘密代码，它们通过输入一次性密码来验证该代码。接下来，您可以为用户启用 TOTP MFA，或将 TOTP 设置为用户的首选 MFA 方法。

当您将用户池配置为需要 TOTP MFA 并且用户在托管登录中注册应用程序时，Amazon Cognito 会自动执行用户流程。Amazon Cognito 提示您的用户选择 MFA 方法，显示 QR 代码来设置身份验证器应用程序，并验证他们的 MFA 注册。在您允许用户在 SMS 和 TOTP MFA 之间进行选择的用户池中，Amazon Cognito 还为您的用户提供了方法选择。

重要

当您将 AWS WAF Web ACL 与用户池关联且您的 Web ACL 中的规则显示验证码时，这可能会导致托管登录 TOTP 注册中出现无法恢复的错误。要创建具有 CAPTCHA 操作且不影响托管登录 TOTP 的规则，请参阅配置您的 AWS WAF 用于管理登录的 Web ACL TOTP MFA。有关 AWS WAF Web ACL 和 Amazon Cognito 的更多信息，请参阅 关联 AWS WAF 带有用户池的 Web ACL。

要使用 AWS 软件开发工具包和亚马逊 Cognito 用户池 API 在自定义用户界面中实现 TOTP MFA，请参阅。 为用户配置 TOTP MFA

要向用户池添加 MFA，请参阅 向用户池添加 MFA。

TOTP MFA 注意事项和限制

  1. Amazon Cognito 通过可生成 TOTP 代码的身份验证器应用程序支持软件令牌 MFA。Amazon Cognito 不支持基于硬件的 MFA。

  2. 当您的用户池要求尚未进行配置的用户提供 TOTP 时，您的用户将收到一个一次性访问令牌，应用程序可使用该令牌为用户激活 TOTP MFA。在用户注册了额外的 TOTP 登录安全要素之前，后续的登录尝试将失败。

    • 通过 SignUp API 操作或通过托管登录来登录用户池的用户，在完成注册时将收到一次性的令牌。

    • 在您创建用户并且用户设置初始密码后，Amazon Cognito 会从托管登录向用户颁发一次性令牌。如果您为用户设置了永久密码，则 Amazon Cognito 会在用户首次登录时颁发一次性令牌。

    • Amazon Cognito 不会向管理员创建的使用或 API 操作登录的用户发放一次性令牌。 InitiateAuth AdminInitiateAuth 在您的用户成功完成质询来设置初始密码后，或者如果您为用户设置永久密码，Amazon Cognito 会立即向用户提出质询来设置 MFA。

  3. 如果用户池中需要 MFA 的用户已收到一次性访问令牌但尚未设置 TOTP MFA，则在设置 MFA 之前，用户无法使用托管登录进行登录。您可以使用来自MFA_SETUP质询InitiateAuth或AssociateSoftwareToken请求AdminInitiateAuth中的session响应值，而不是访问令牌。

  4. 如果您的用户已设置 TOTP，则他们可以将其用于 MFA，即使您以后停用用户池的 TOTP。

  5. 亚马逊 Cognito 仅接受使用哈希函数生成代码的身份验证器应用程序的 TOTP。 HMAC-SHA1 使用 SHA-256 哈希算法生成的代码会返回Code mismatch错误。

为用户配置 TOTP MFA

当用户首次登录时，您的应用程序使用他们的一次性访问令牌生成 TOTP 私钥，并以文本或二维码格式将其呈现给用户。您的用户配置其身份验证器应用程序并为后续登录尝试提供 TOTP。您的应用程序或托管登录在 MFA 质询响应中向 Amazon Cognito 提交 TOTP。

在某些情况下，托管登录会提示新用户设置 TOTP 身份验证器。有关更多信息，请参阅用户运行时的 MFA 逻辑详情。

关联 TOTP 软件令牌

要关联 TOTP 令牌，请向用户发送一个必须使用一次性密码来验证的秘密代码。关联令牌需要执行三个步骤。

  1. 当您的用户选择 TOTP 软件令牌 MFA 时，AssociateSoftwareToken请致电返回为用户账户生成的唯一共享密钥代码。您可以使用访问令牌或会话字符串进行授权 AssociateSoftwareToken 。

  2. 您的应用程序向用户呈现私钥或您从私钥生成的二维码。您的用户必须通过扫描 TOTP-generating 应用程序从私钥生成的二维码或手动输入密钥来将密钥输入到 Google Authenticator 等应用中。

  3. 您的用户用身份验证器应用程序（例如 Google Authenticator）输入密钥或扫描二维码，该应用程序开始生成代码。

验证 TOTP 令牌

接下来验证 TOTP 令牌。要求您的用户提供示例代码并将其提供给 Amazon Cognito 服务，以确认用户成功生成 TOTP 代码，如下所示。

  1. 您的应用程序会提示用户输入代码，以证明他们已正确设置了身份验证器应用程序。

  2. 用户的身份验证器应用程序显示一个临时密码。身份验证器应用程序根据您提供给用户的密钥生成密码。

  3. 用户输入他们的临时密码。您的应用程序在 VerifySoftwareToken API 请求中将临时密码传递给 Amazon Cognito。

  4. Amazon Cognito 保留与用户关联的密钥，并生成 TOTP 并将其与用户提供的 TOTP 进行比较。如果匹配，VerifySoftwareToken 返回 SUCCESS 响应。

  5. Amazon Cognito 将 TOTP 要素与用户关联起来。

  6. 如果 VerifySoftwareToken 操作返回 ERROR 响应，请确保用户的时钟正确且没有超过最大重试次数。Amazon Cognito 接受在尝试前后 30 秒之内的 TOTP 令牌，以容许轻微的时钟偏差。解决问题后，请重试该 VerifySoftwareToken 操作。

使用 TOTP MFA 登录

此时，您的用户可使用基于时间的一次性密码登录。过程如下所述。

  1. 用户将输入其用户名和密码来登录客户端应用程序。

  2. TOTP MFA 质询被调用，您的应用程序提示用户输入临时密码。

  3. 您的用户从关联的 TOTP-generating应用程序获取临时密码。

  4. 您的用户在您的客户端应用程序中输入 TOTP 代码。您的应用程序通知 Amazon Cognito 服务以验证该代码。对于每次登录，都RespondToAuthChallenge应调用以获取对新的 TOTP 身份验证质询的响应。

  5. 如果令牌通过 Amazon Cognito 验证，则登录成功，您的用户可以继续完成身份验证流程。

删除 TOTP 令牌

最后，您的应用程序应允许您的用户停用他们的 TOTP 配置。要删除用户的 TOTP 软件令牌，请使用AdminDeleteSoftwareToken。删除用户的软件令牌后，他们将无法再使用 TOTP MFA 登录，可以注册新的软件令牌。当您的用户无法访问其 TOTP-generating 设备时，例如手机丢失或重置时，请使用此操作。当您的用户池需要 MFA 且没有其他可用因素时，Amazon Cognito 会在用户下次登录时返回MFA_SETUP质询。当您的用户还有其他可用因素（例如 SMS 消息 MFA）时，登录会退回到该因素。

如果您的用户仍然可以访问他们的 TOTP-generating 设备，则无需删除他们的软件令牌。当您的用户验证新软件令牌时，Amazon Cognito 会取消关联现有软件令牌。要为您的用户停用 TOTP MFA，请致电SetUserMFAPreference将您的用户修改为不使用 MFA，或仅使用 SMS MFA。

  1. 在您的应用程序中为想要重置 MFA 的用户创建界面。在此界面中提示用户输入密码。

  2. 如果亚马逊 Cognito 返回 TOTP MFA 质询，请使用更新用户的 MFA 偏好。 SetUserMFAPreference

  3. 在您的应用程序中，告知您的用户他们已停用 MFA 并提示他们重新登录。

配置您的 AWS WAF 用于管理登录的 Web ACL TOTP MFA

当您将 AWS WAF Web ACL 与用户池关联且您的 Web ACL 中的规则显示验证码时，这可能会导致托管登录 TOTP 注册中出现无法恢复的错误。 AWS WAF 验证码规则仅对托管登录和经典托管用户界面中的 TOTP MFA 有此影响。SMS MFA 不受影响。

当 CAPTCHA 规则不允许用户完成 TOTP MFA 设置时，Amazon Cognito 会显示以下错误。

由于 WAF captcha，不允许请求。

当 AWS WAF 提示输入验证码以AssociateSoftwareToken响应用户池在后台发出VerifySoftwareToken的 API 请求时，就会出现此错误。要创建一个包含 CAPTCHA 操作且不影响托管登录页面中 TOTP 的规则，请从您的规则中的 CAPTCHA 操作中排除 x-amzn-cognito-operation-name 标头的 AssociateSoftwareToken 和 VerifySoftwareToken 值。

以下屏幕截图显示了一个示例 AWS WAF 规则，该规则将 CAPTCHA 操作应用于x-amzn-cognito-operation-name标头值不为或的所有请求。AssociateSoftwareToken VerifySoftwareToken

将验证码操作应用于标x-amzn-cognito-operation-name头值不为或的所有请求的 AWS WAF 规则的AssociateSoftwareToken屏幕截图。VerifySoftwareToken

有关 AWS WAF 网络 ACL 和 Amazon Cognito 的更多信息，请参阅。关联 AWS WAF 带有用户池的 Web ACL