本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# TOTP 軟體權杖 MFA
當您在使用者集區中設定 TOTP 軟體字符 MFA 時，使用者以使用者名稱和密碼登入，然後使用 TOTP 完成身分驗證。在您的使用者設定並驗證使用者名稱和密碼之後，他們就可以為 MFA 啟用 TOTP 軟體權杖。如果您的應用程式使用 Amazon Cognito 受管登入來登入使用者，您的使用者會提交其使用者名稱和密碼，然後在其他登入頁面上提交 TOTP 密碼。
您可以在 Amazon Cognito 主控台中或使用 Amazon Cognito API 操作，為您的使用者集區啟用 TOTP MFA。在使用者集區層級，您可以呼叫 [SetUserPoolMfaConfig](https://docs.aws.amazon.com/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 也會為您的使用者提供方法選擇。
**重要**
當您的 AWS WAF Web ACL 與使用者集區相關聯，且 Web ACL 中的規則顯示 CAPTCHA 時，這可能會導致受管登入 TOTP 註冊發生無法復原的錯誤。若要建立具有 CAPTCHA 動作且不會影響受管登入 TOTP 的規則，請參閱 [設定您的 AWS WAF Web ACL 以進行受管登入 TOTP MFA](#totp-waf)。如需 AWS WAF Web ACL 和 Amazon Cognito 的相關資訊，請參閱[將 AWS WAF Web ACL 與使用者集區建立關聯](user-pool-waf.md)。
若要使用 AWS SDK 和 [Amazon Cognito 使用者集區 API](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/Welcome.html) 在自訂建置的 UI 中實作 TOTP MFA，請參閱 [為使用者設定 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 時，使用者會收到一次性存取權杖，您的應用程式可用它來為該使用者啟用 TOTP MFA。後續的登入嘗試將會失敗，直到使用者註冊其他 TOTP 登入要素。
+ 使用 `SignUp` API 操作或透過受管登入在使用者集區中註冊的使用者，會在使用者完成註冊時收到一次性字符。
+ 在您建立使用者且使用者設定其初始密碼後，Amazon Cognito 會從受管登入向使用者發出一次性字符。如果您為使用者設定了永久性密碼，Amazon Cognito 會在使用者首次登入時發放一次性權杖。
+ Amazon Cognito 不會向管理員建立的使用者 (這些使用者使用 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) 或 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) API 操作) 發放一次性權杖。您的使用者在成功完成設定其初始密碼的挑戰之後，或者如果您為使用者設定了永久性密碼，Amazon Cognito 會立即要求使用者設定 MFA。
1. 如果使用者集區中需要 MFA 的使用者已收到一次性存取權杖，但尚未設定 TOTP MFA，則使用者必須先設定 MFA，才能使用受管登入來登入。您可以使用來自 `MFA_SETUP` 的 `session` 回應值挑戰 [AssociateSoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html) 請求中的 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) 或 [AdminInitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminInitiateAuth.html) 以取代存取字符。
1. 如果您的使用者已設定 TOTP，即使您稍後停用使用者集區的 TOTP，使用者仍可將其用於 MFA。
1. Amazon Cognito 僅接受來自使用 HMAC-SHA1 雜湊函數產生程式碼之驗證器應用程式的 TOTPs。使用 SHA-256 雜湊產生的代碼會傳回 `Code mismatch` 錯誤。
## 為使用者設定 TOTP MFA
當使用者首次登入時，您的應用程式將使用其一次性存取字符以產生 TOTP 私有金鑰，並以文字或 QR 碼格式呈現給使用者。您的使用者設定其驗證器應用程式，並為後續的登入嘗試提供 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 軟體字符關聯
若要關聯 TOTP 權杖，請傳送秘密代碼給您的使用者，秘密代碼必須使用一次性密碼進行驗證。關聯權杖需要三個步驟。
1. 當您的使用者選擇 TOTP 軟體字符 MFA 時，請呼叫 [AssociateSoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html)，為該使用者帳戶傳回唯一產生的共用私密金鑰代碼。您可以使用存取權杖或工作階段字串授權 AssociateSoftwareToken。
1. 您的應用程式向使用者顯示私有金鑰或是從私有金鑰產生的 QR 代碼。您的使用者必須將金鑰輸入至產生 TOTP 的應用程式，例如 Google Authenticator，方法是掃描應用程式從私有金鑰產生的 QR 碼，或手動輸入金鑰。
1. 您的使用者輸入金鑰，或將 QR 代碼掃描至驗證器應用程式 (如 Google Authenticator) 中，然後該應用程式開始產生代碼。
### 驗證 TOTP 字符
接下來，驗證 TOTP 權杖。向使用者請求範本代碼並將其提供給 Amazon Cognito 服務，以確認使用者是否已成功產生 TOTP 代碼，如下所示。
1. 您的應用程式會提示使用者輸入代碼，以證明其已正確設定驗證器應用程式。
1. 使用者的驗證器應用程式會顯示一個臨時密碼。驗證器應用程式的密碼以您給予使用者的私密金鑰為基礎。
1. 您的使用者輸入其臨時密碼。您的應用程式在 `[VerifySoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifySoftwareToken.html)` API 請求中，將臨時密碼傳遞給 Amazon Cognito。
1. Amazon Cognito 保留了與使用者關聯的私密金鑰，產生 TOTP 並將其與您的使用者提供的私密金鑰進行比較。如果兩者相符，`VerifySoftwareToken` 會傳回 `SUCCESS` 回應。
1. Amazon Cognito 將 TOTP 要素與使用者建立關聯。
1. 如果 `VerifySoftwareToken` 操作傳回 `ERROR` 回應，請確定使用者的時鐘是正確的，而且沒有超過最大重試次數。Amazon Cognito 接受嘗試之前或之後 30 秒內的 TOTP 權杖，以解決微小的時鐘偏差問題。當您解決此問題後，請再次嘗試 VerifySoftwareToken 操作。
### 使用 TOTP MFA 來登入
此時，您的使用者會使用以時間為基礎的一次性密碼登入。程序如下。
1. 您的使用者要輸入其使用者名稱和密碼來登入您的用戶端應用程式。
1. 您的應用程式會叫用 TOTP MFA 挑戰，並提示使用者輸入臨時密碼。
1. 使用者從關聯的 TOTP 產生應用程式取得臨時密碼。
1. 使用者在您的用戶端應用程式中輸入 TOTP 代碼。您的應用程式通知 Amazon Cognito 服務加以驗證。每次登入都應呼叫 [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html)，以取得對新 TOTP 驗證挑戰的回應。
1. 如果權杖經過 Amazon Cognito 驗證，則登入成功，使用者可以繼續進行身分驗證流程。
### 移除 TOTP 權杖
最後，您的應用程式應允許使用者停用其 TOTP 組態。您目前無法刪除使用者的 TOTP 軟體權杖。若要取代使用者的軟體權杖，請關聯並驗證新的軟體權杖。若要停用使用者的 TOTP MFA，請呼叫 [SetUserMFAPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html) 修改您的使用者，使其不使用 MFA，或僅使用 SMS MFA。
1. 在您的應用程式中，為想要重設 MFA 的使用者建立一個介面。在此介面中提示使用者輸入其密碼。
1. 如果 Amazon Cognito 傳回 TOTP MFA 挑戰，請使用 [SetUserMFAPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html) 更新使用者的 MFA 偏好設定。
1. 在您的應用程式中，告知使用者他們已停用 MFA，並提示他們再次登入。
## 設定您的 AWS WAF Web ACL 以進行受管登入 TOTP MFA
當您的 AWS WAF Web ACL 與使用者集區相關聯，且 Web ACL 中的規則顯示 CAPTCHA 時，這可能會導致受管登入 TOTP 註冊時發生無法復原的錯誤。 AWS WAF CAPTCHA 規則*只會*對受管登入和傳統託管 UI 中的 TOTP MFA 產生此影響。SMS MFA 不受影響。
當您的 CAPTCHA 規則無法讓使用者完成 TOTP MFA 設定時，Amazon Cognito 會顯示下列錯誤。
Request not allowed due to WAF captcha. (由於 WAF captcha，不允許請求。)
當 AWS WAF 提示 CAPTCHA 回應使用者集區在背景提出的 [AssociateSoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AssociateSoftwareToken.html) 和 [VerifySoftwareToken](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_VerifySoftwareToken.html) API 請求時，就會產生此錯誤。若要建立具有 CAPTCHA 動作且不會影響受管登入頁面中 TOTP 的規則，請在規則中排除 `AssociateSoftwareToken` `VerifySoftwareToken` 和 的`x-amzn-cognito-operation-name`標頭值。
下列螢幕擷取畫面顯示範例 AWS WAF 規則，會將 CAPTCHA 動作套用至沒有 `AssociateSoftwareToken`或 `x-amzn-cognito-operation-name`標頭值的所有請求`VerifySoftwareToken`。
如需 AWS WAF Web ACLs 和 Amazon Cognito 的詳細資訊，請參閱 [將 AWS WAF Web ACL 與使用者集區建立關聯](user-pool-waf.md)。