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

# TOTP 软件令牌 MFA
<a name="user-pool-settings-mfa-totp"></a>

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

您可以在 Amazon Cognito 控制台中为用户池激活 TOTP MFA，也可以使用 Amazon Cognito API 操作来激活。在用户池级别，您可以调用[SetUserPoolMfaConfig](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_SetUserPoolMfaConfig.html)配置 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 还为您的用户提供了方法选择。

**重要**  
当您的 Amazon WAF Web ACL 与用户池相关联，并且您的 Web ACL 中的规则显示了验证码时，这可能会导致托管登录 TOTP 注册中出现不可恢复的错误。要创建具有 CAPTCHA 操作且不影响托管登录 TOTP 的规则，请参阅[为托管登录 TOTP MFA 配置您的 Amazon WAF 网页 ACL](#totp-waf)。有关 Amazon WAF 网络 ACLs 和 Amazon Cognito 的更多信息，请参阅。[将 Amazon WAF Web ACL 与用户池关联](user-pool-waf.md)

要使用软件开发工具包和 Amazon Co [gnito 用户池 API 在自定义用户界面 Amazon 中实现 TOTP MFA，请参](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/Welcome.html)阅。[为用户配置 TOTP MFA](#totp-mfa-set-up-api)

要向用户池添加 MFA，请参阅 [向用户池添加 MFA](user-pool-settings-mfa.md)。

**TOTP MFA 注意事项和限制**

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

1. 当您的用户池要求尚未进行配置的用户提供 TOTP 时，您的用户将收到一个一次性访问令牌，应用程序可使用该令牌为用户激活 TOTP MFA。在用户注册了额外的 TOTP 登录安全要素之前，后续的登录尝试将失败。
   + 通过 `SignUp` API 操作或通过托管登录来登录用户池的用户，在完成注册时将收到一次性的令牌。
   + 在您创建用户并且用户设置初始密码后，Amazon Cognito 会从托管登录向用户颁发一次性令牌。如果您为用户设置了永久密码，则 Amazon Cognito 会在用户首次登录时颁发一次性令牌。
   + Amazon Cognito 不会向使用或 API 操作登录的管理员创建的用户发放一次性令牌。[InitiateAuth[AdminInitiateAuth](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html)](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)在您的用户成功完成质询来设置初始密码后，或者如果您为用户设置永久密码，Amazon Cognito 会立即向用户提出质询来设置 MFA。

1. 如果用户池中需要 MFA 的用户已收到一次性访问令牌但尚未设置 TOTP MFA，则在设置 MFA 之前，用户无法使用托管登录进行登录。您可以代替访问令牌，而是在请求中使用`MFA_SETUP`质询[InitiateAuth](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)或[AssociateSoftwareToken](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html)请求[AdminInitiateAuth](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html)中的`session`响应值。

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

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

## 为用户配置 TOTP MFA
<a name="totp-mfa-set-up-api"></a>

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

在某些情况下，托管登录会提示新用户设置 TOTP 身份验证器。有关更多信息，请参阅[用户运行时的 MFA 逻辑详情](user-pool-settings-mfa.md#user-pool-settings-mfa-user-outcomes)。

**Topics**
+ [

### 关联 TOTP 软件令牌
](#user-pool-settings-mfa-totp-associate-token)
+ [

### 验证 TOTP 令牌
](#user-pool-settings-mfa-totp-verification)
+ [

### 使用 TOTP MFA 登录
](#user-pool-settings-mfa-totp-sign-in)
+ [

### 删除 TOTP 令牌
](#user-pool-settings-mfa-totp-remove)

### 关联 TOTP 软件令牌
<a name="user-pool-settings-mfa-totp-associate-token"></a>

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

1. 当您的用户选择 TOTP 软件令牌 MFA 时，[AssociateSoftwareToken](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html)调用返回为用户帐户生成的唯一共享密钥代码。您可以使用访问令牌或会话字符串进行授权 AssociateSoftwareToken 。

1. 您的应用程序向用户呈现私钥或您从私钥生成的二维码。您的用户必须将密钥输入到 TOTP 生成应用程序（如 Google Authenticator）中，方式可以是扫描您的应用程序根据私有密钥生成的二维码，也可以是手动输入该密钥。

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

### 验证 TOTP 令牌
<a name="user-pool-settings-mfa-totp-verification"></a>

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

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

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

1. 用户输入他们的临时密码。您的应用程序在 `[VerifySoftwareToken](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_VerifySoftwareToken.html)` API 请求中将临时密码传递给 Amazon Cognito。

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

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

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

### 使用 TOTP MFA 登录
<a name="user-pool-settings-mfa-totp-sign-in"></a>

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

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

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

1. 您的用户从关联的 TOTP 生成应用程序获取临时密码。

1. 您的用户在您的客户端应用程序中输入 TOTP 代码。您的应用程序通知 Amazon Cognito 服务以验证该代码。对于每次登录，都[RespondToAuthChallenge](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html)应调用以获取对新 TOTP 身份验证质询的响应。

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

### 删除 TOTP 令牌
<a name="user-pool-settings-mfa-totp-remove"></a>

最后，您的应用程序应允许您的用户停用他们的 TOTP 配置。当前，您无法删除用户的 TOTP 软件令牌。要替换用户的软件令牌，请关联并验证新的软件令牌。要为用户停用 TOTP MFA，请致电[SetUserMFAPreference](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html)将您的用户修改为不使用 MFA 或仅使用 SMS MFA。

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

1. 如果 Amazon Cognito 返回 TOTP MFA 质询，请将用户的 MFA 偏好设置更新为。[SetUserMFAPreference](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html)

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

## 为托管登录 TOTP MFA 配置您的 Amazon WAF 网页 ACL
<a name="totp-waf"></a>

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

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

由于 WAF captcha，不允许请求。

当你的用户池在后台发出的 [VerifySoftwareToken](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_VerifySoftwareToken.html)API 请求时 Amazon WAF 提示输入验证码时，就会出现此错误。[AssociateSoftwareToken](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html)要创建一个包含 CAPTCHA 操作且不影响托管登录页面中 TOTP 的规则，请从您的规则中的 CAPTCHA 操作中排除 `x-amzn-cognito-operation-name` 标头的 `AssociateSoftwareToken` 和 `VerifySoftwareToken` 值。

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

![\[一条 Amazon WAF 规则的屏幕截图，该规则将验证码操作应用于x-amzn-cognito-operation-name标头值不为或的所有请求。AssociateSoftwareToken VerifySoftwareToken\]](http://docs.amazonaws.cn/cognito/latest/developerguide/images/cup-WAF-rule-TOTP.png)


有关 Amazon WAF 网络 ACLs 和 Amazon Cognito 的更多信息，请参阅。[将 Amazon WAF Web ACL 与用户池关联](user-pool-waf.md)