TOTP 软件令牌 MFA - Amazon Cognito
在 Amazon Cognito 用户池 API 中为用户配置 MFA为托管 UI TOTP MFA 配置 Amazon WAF Web ACL
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

TOTP 软件令牌 MFA

当您在用户池中设置了 TOTP 软件令牌 MFA 时，您的用户通过用户名和密码登录，然后使用 TOTP 完成身份验证。用户设置并验证用户名和密码后，就可以为 MFA 激活 TOTP 软件令牌。如果应用程序使用 Amazon Cognito 托管 UI 来登录用户，则用户提交用户名和密码，然后在额外的登录页面上提交 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 并且用户在托管 UI 中注册应用程序时，Amazon Cognito 会自动执行用户流程。Amazon Cognito 提示您的用户选择 MFA 方法，显示 QR 代码来设置身份验证器应用程序，并验证他们的 MFA 注册。在您允许用户在 SMS 和 TOTP MFA 之间进行选择的用户池中，Amazon Cognito 还为您的用户提供了方法选择。有关托管 UI 注册体验的更多信息，请参阅 如何在 Amazon Cognito 托管 UI 中注册新账户。

重要

当您将 Amazon WAF Web ACL 与用户池关联并且 Web ACL 中的规则提供 CAPTCHA 时，这可能会导致托管 UI TOTP 注册中出现不可恢复的错误。要创建具有 CAPTCHA 操作且不影响托管 UI TOTP 的规则，请参阅 为托管 UI TOTP MFA 配置 Amazon WAF Web ACL。有关 Amazon WAF Web ACL 和 Amazon Cognito 的更多信息，请参阅 将 Amazon WAF Web ACL 与用户池相关联。

要在使用 Amazon Cognito API 的自定义 UI 中实施 TOTP MFA，请参阅 在 Amazon Cognito 用户池 API 中为用户配置 MFA。

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

TOTP MFA 注意事项和限制

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

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

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

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

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

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

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

  5. Amazon Cognito 仅接受来自使用 SHA-1 哈希函数生成代码的身份验证器应用程序的 TOTP。使用 SHA-256 哈希生成的代码会返回 Code mismatch 错误。

在 Amazon Cognito 用户池 API 中为用户配置 MFA

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

关联 TOTP 软件令牌

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

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

  2. 您的应用程序向用户呈现私钥或您从私钥生成的二维码。用户必须将密钥输入到一个生成 TOTP 的应用程序（如 Google Authenticator）中。您可以使用 libqrencode 生成二维码。

  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 生成应用程序获取临时密码。

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

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

删除 TOTP 令牌

最后，您的应用程序应允许您的用户停用他们的 TOTP 配置。当前，您无法删除用户的 TOTP 软件令牌。要替换用户的软件令牌，请关联并验证新的软件令牌。要为用户停用 TOTP MFA，请调用 mf SetUserapReference 将您的用户修改为不使用 MF A 或仅使用 SMS MFA。

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

  2. 如果 Amazon Cognito 返回 TOTP MFA 质询，请使用 mfapReference 更新用户的 MFA 偏好。SetUser

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

为托管 UI TOTP MFA 配置 Amazon WAF Web ACL

当您将 Amazon WAF Web ACL 与用户池关联并且 Web ACL 中的规则提供 CAPTCHA 时，这可能会导致托管 UI TOTP 注册中出现不可恢复的错误。Amazon WAFCAPTCHA 规则仅以这种方式影响托管 UI 中的 TOTP MFA。SMS MFA 不受影响。

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

由于 WAF captcha，不允许请求。

当你的用户池在后台发出的 VerifySoftwareTokenAPI 请求时Amazon WAF提示输入验证码时，就会出现此错误。AssociateSoftwareToken要创建具有 CAPTCHA 操作且不影响托管 UI TOTP 的规则，请从您的规则中的 CAPTCHA 操作中排除 AssociateSoftwareToken 和 VerifySoftwareToken 的 x-amzn-cognito-operation-name 标头值。

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

一个 Amazon WAF 规则的屏幕截图，该规则将 CAPTCHA 操作应用于所有没有 AssociateSoftwareToken 或 VerifySoftwareToken 的 x-amzn-cognito-operation-name 标头值的请求。

有关 Amazon WAF Web ACL 和 Amazon Cognito 的更多信息，请参阅 将 Amazon WAF Web ACL 与用户池相关联。