TOTP 软件令牌 MFA - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

TOTP 软件令牌 MFA

重要

用户无法在 Amazon Cognito 托管 UI 中设置基于时间的一次性密码 (TOTP) 多重验证 (MFA)。您的应用程序必须使用 Amazon Cognito API 才能按照关联 TOTP 软件令牌验证 TOTP 令牌中所述的设置步骤完成操作。

当您在用户池中设置了 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 方法。

要向用户池添加 MFA,请参阅 向用户池添加 MFA

TOTP MFA 注意事项和限制

  1. Amazon Cognito 托管 UI 目前不支持自助 TOTP 设置。在应用程序关联并验证 TOTP 软件令牌后,您的用户可以在托管 UI 中提供其 TOTP。

  2. Amazon Cognito 通过代码生成器应用程序支持软件令牌 MFA。Amazon Cognito 不支持基于硬件的 MFA。

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

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

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

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

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

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

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

关联 TOTP 软件令牌

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

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

  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 令牌:

  1. 客户端应用程序应要求用户输入其密码。

  2. 如果密码正确,则删除 TOTP 令牌。

    注意

    目前 API 中不支持删除 TOTP 软件令牌操作。计划在未来版本中提供此功能。使用 SetUserMFAPreference 为单独的用户禁用 TOTP MFA。