向用户池添加 MFA - Amazon Cognito
需知信息用户 MFA 首选项MFA 逻辑配置 MFA
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

向用户池添加 MFA

MFA 将您具有的某种 身份验证因素添加到您已知的 初始因素（通常是用户名和密码）中。对于使用密码作为主要身份验证因素的用户，您可以选择将短信文本消息、电子邮件消息或基于时间的一次性密码（TOTP）作为他们登录的额外安全因素。

多重身份验证（MFA）可提高应用程序中本地用户的安全性。对于联合用户，Amazon Cognito 会将所有身份验证过程委托给 IdP，并且不会为他们提供额外的身份验证因素。

注意

新用户首次登录应用程序时，Amazon Cognito 会发出 OAuth 2.0 令牌，即使您的用户池要求使用 MFA 也是如此。您的用户首次登录时的第二个身份验证因素是他们对 Amazon Cognito 发送给他们的验证消息的确认。如果您的用户池要求使用 MFA，Amazon Cognito 会提示您的用户注册一个额外的登录因素，以便在第一次之后的每次登录尝试期间使用。

借助自适应身份验证，可以将用户池配置为响应增加的风险级别需要额外的身份验证因素。要向用户池添加自适应身份验证，请参阅 具备威胁防护的高级安全功能。

将用户池的 MFA 设置为 required 时，所有用户都必须完成 MFA 才能登录。要登录，每个用户至少设置一个 MFA 安全因素。当需要进行 MFA 时，您必须在用户引导中包含 MFA 设置，以便您的用户池允许他们登录。

当您将 MFA 设置为必需时，托管登录会提示用户设置 MFA。当您在用户池中将 MFA 设置为可选时，托管登录不会提示用户。要使用可选的 MFA，您必须在应用程序中构建一个界面，以提示用户选择他们需要设置 MFA，然后引导他们完成 API 输入以验证他们的额外登录因素。

主题

有关用户池 MFA 的需知信息

在设置 MFA 之前，请考虑以下情况：

  • 用户可以选择使用 MFA，或 使用无密码因素进行登录。

    • 在支持一次性密码或通行密钥的用户池中，无法将 MFA 设置为必需。

    • 当用户池要求启用 MFA 时，您无法将 WEB_AUTHN、EMAIL_OTP 或 SMS_OTP 添加到 AllowedFirstAuthFactors 中。在 Amazon Cognito 控制台中，您无法编辑基于选择的登录选项以包含无密码因素。

    • 当用户池要求启用 MFA 时，所有应用程序客户端中基于选择的登录仅提供 PASSWORD 和 PASSWORD_SRP 两种因素。有关用户名密码流程的更多信息，请参阅本指南身份验证一章中的使用永久密码登录和使用永久密码和安全有效载荷登录。

    • 在 MFA 为可选的用户池中，已配置 MFA 因素的用户在使用基于选择的登录时，只能通过用户名密码的身份验证流程进行登录。这些用户有资格使用所有基于客户端的登录流程。

    下表描述了用户池的 MFA 设置及用户对 MFA 因素的配置对用户使用无密码因素登录的能力的影响。

    用户池 MFA 设置 用户 MFA 状态 Webauthn/OTP 可用 密码登录后提示进行 MFA 可以使用 WebAuthn/OTP 登录
    必需 已配置 否 支持 否
    必需 未配置 否 否（无法登录） 否
    可选 已配置 可以设置 WebAuthn 但无法使用通行密钥登录 支持 否
    可选 未配置 支持 否 支持
    Off 任何 支持 否 支持

  • 用户首选 MFA 方法会影响他们可用于恢复密码的方法。首选 MFA 方式为电子邮件的用户无法通过电子邮件接收密码重置代码。首选 MFA 方式为短信的用户无法通过短信接收密码重置代码。

    当用户不符合条件，无法使用首选密码重置方法时，您的密码恢复设置必须提供替代选项。例如，您的恢复机制可能将电子邮件列为第一优先选项，而电子邮件 MFA 可能是您的用户池中的一个选项。在这种情况下，添加短信消息账户恢复作为第二个选项，或者使用管理 API 操作为这些用户重置密码。

    对于没有有效恢复方式的用户发起的密码重置请求，Amazon Cognito 会返回 InvalidParameterException 错误响应。

    UpdateUserPool 的请求正文示例展示了一种 AccountRecoverySetting，其中当电子邮件密码重置方式不可用时，用户可回退到通过短信进行恢复。

  • 用户无法在同一电子邮件地址或电话号码上接收 MFA 验证码和密码重置验证码。如果他们使用电子邮件消息中的一次性密码（OTP）进行 MFA，则必须使用短信进行账户恢复。如果他们使用短信中的 OTP 进行 MFA，则必须使用电子邮件消息进行账户恢复。在具有 MFA 的用户池中，如果用户有电子邮件地址的属性但没有电话号码，或者有电话号码但没有电子邮件地址，则他们可能无法完成自助密码恢复。

    要防止用户无法在使用此配置的用户池中重置密码的情况，请设置 email 和 phone_number 属性（按需设置）。或者，您可以设置相关流程，在用户注册时或管理员创建用户配置文件时，始终收集并设置这些属性。当用户同时具备这两个属性时，Amazon Cognito 会自动将密码重置验证码发送到不是用户 MFA 因素的目的地。

  • 当您在用户池中激活 MFA 并选择短信或电子邮件消息作为第二安全因素时，可以向尚未在 Amazon Cognito 中验证的电话号码或电子邮件属性发送消息。用户完成 MFA 后，Amazon Cognito 会将其 phone_number_verified 或 email_verified 属性设置为 true。

  • 在五次尝试提交 MFA 代码均未成功后，Amazon Cognito 会开始如失败登录尝试的锁定行为中所描述的指数超时锁定过程。

  • 如果您的账户所在的 SMS 沙盒，位于包含用户池的 Amazon Simple Notification Service（Amazon SNS）资源的 Amazon Web Services 区域中，您必须在 Amazon SNS 中验证电话号码，然后才能发送短信。有关更多信息，请参阅Amazon Cognito 用户池的短信设置。

  • 为了更改用户的 MFA 状态以响应威胁防护功能检测到的事件，请激活 MFA 并在 Amazon Cognito 用户池控制台中将其设置为可选。有关更多信息，请参阅具备威胁防护的高级安全功能。

  • 电子邮件和短信消息要求您的用户分别具有电子邮件地址和电话号码属性。您可以在用户池中将 email 或 phone_number 设置为必需的属性。在这种情况下，除非用户提供电话号码，否则他们无法完成注册。如果您未将这些属性设置为必需，但想要进行电子邮件或短信消息 MFA，则可以在用户注册时提示他们输入电子邮件地址或电话号码。妥善的做法是将用户池配置为自动向用户发送消息来验证这些属性。

    如果用户通过短信或电子邮件成功接收了临时验证码，并在 VerifyUserAttribute API 请求中返回了该验证码，则 Amazon Cognito 会将电话号码或电子邮件地址视为已验证。或者，您的团队可以设置电话号码，并使用执行 AdminUpdateUserAttributes API 请求的管理应用程序将其标记为已验证。

  • 如果您已将 MFA 设置为必需且激活了多个身份验证因素，则 Amazon Cognito 会提示新用户选择他们想要使用的 MFA 因素。用户必须有电话号码才能设置短信消息 MFA，必须有电子邮件地址才能设置电子邮件消息 MFA。如果用户没有为任何基于消息的可用 MFA 定义属性，则 Amazon Cognito 会提示他们设置 TOTP MFA。选择 MFA 因素（SELECT_MFA_TYPE）的提示，以及设置所选因素（MFA_SETUP）的提示会作为 InitiateAuth 和 AdminInitiateAuth API 操作的质询响应出现。

用户 MFA 首选项

用户可以设置多个 MFA 因素。只能激活一个因素。您可以在用户池设置中或从用户提示为用户选择有效的 MFA 首选项。当用户池设置和他们自己的用户级设置满足以下条件时，用户池会提示用户输入 MFA 验证码：

  1. 您可以在用户池中将 MFA 设置为可选或必需。

  2. 用户具有有效的 email 或 phone_number 属性，或者已为 TOTP 设置身份验证器应用程序。

  3. 至少有一个 MFA 因素处于活动状态。

  4. 一个 MFA 因素设置为首选。

用户池设置及其对 MFA 选项的影响

用户池的配置会影响用户可以选择的 MFA 方法。以下是一些会影响用户设置 MFA 能力的用户池设置。

  • 在 Amazon Cognito 控制台登录菜单中的多重身份验证配置中，您可以将 MFA 设置为可选或必需，也可以将其关闭。此设置的 API 等效项是 CreateUserPool、UpdateUserPool 和 SetUserPoolMfaConfig 的 MfaConfiguration 参数。

    此外，在多重身份验证配置中，MFA 方法设置决定了用户可以设置的 MFA 因素。此设置的 API 等效项是 SetUserPoolMfaConfig 操作。

  • 在用户账户恢复下的登录菜单中，您可以配置用户池向忘记密码的用户发送消息的方式。用户的 MFA 方法不能与用户池用于发送“忘记密码”验证码的 MFA 传送方式相同。“忘记密码”验证码的传送方式的 API 参数是 CreateUserPool 和 UpdateUserPool 的 AccountRecoverySetting 参数。

    例如，当恢复选项为仅使用电子邮件时，用户无法设置电子邮件 MFA。这是因为在同一个用户池中，您无法既启用电子邮件 MFA 又将恢复选项设置为仅使用电子邮件。当您将此选项设置为如果电子邮件可用，则使用电子邮件发送，否则使用短信时，电子邮件是优先恢复选项，但是当用户不符合通过电子邮件进行恢复的条件时，您的用户池可以回退到短信形式。在这种情况下，用户可以将电子邮件 MFA 设置为首选，并且只在尝试重置密码时才接收短信。

  • 如果您只将一种 MFA 方法设置为可用，则无需管理用户 MFA 首选项。

  • 激活的短信配置会自动使短信成为用户池中的可用 MFA 方法。

    用户池中包含您自己的 Amazon SES 资源的有效电子邮件配置以及基础版或增值版功能计划，可自动使电子邮件消息成为用户池中的可用 MFA 方法。

  • 在用户池中将 MFA 设置为必需时，用户无法启用或禁用任何 MFA 方法。您只能设置首选方法。

  • 当您在用户池中将 MFA 设置为可选时，托管登录不会提示用户设置 MFA，而是在用户拥有首选 MFA 方法时，提示用户输入 MFA 验证码。

  • 当您激活威胁防护并在全功能模式下配置自适应身份验证响应时，在您的用户池中 MFA 必须是可选的。自适应身份验证的其中一个响应选项是要求其登录尝试被评估为包含一定风险级别的用户进行 MFA。

    控制台的注册菜单中的必填属性设置决定了用户是否必须提供电子邮件地址或电话号码才能注册您的应用程序。当用户具有相应属性时，电子邮件和短信将成为符合条件的 MFA 因素。CreateUserPool 的 Schema 参数根据需要设置属性。

  • 当您在用户池中将 MFA 设置为必需且用户使用托管登录进行登录时，Amazon Cognito 会提示他们从用户池的可用方法中选择 MFA 方法。托管登录负责收集电子邮件地址或电话号码并设置 TOTP。下图展示了 Amazon Cognito 向用户提供的选项背后的逻辑。

为用户配置 MFA 首选项

您可以在具有访问令牌授权的自助服务模式中为用户配置 MFA 首选项，或者在具有管理 API 操作的管理员管理模式中为用户配置 MFA 首选项。这些操作启用或禁用 MFA 方法，并将多种方法之一设置为首选选项。在用户设置 MFA 首选项后，Amazon Cognito 会在登录时提示他们提供来自他们首选 MFA 方法的验证码。未设置首选项的用户会收到在 SELECT_MFA_TYPE 质询中选择首选方法的提示。

  • 在用户自助服务模式或公共应用程序中，使用已登录用户的访问令牌来授权的 SetUserMfaPreference 用于设置 MFA 配置。

  • 在管理员管理的应用程序或机密应用程序中，使用管理 Amazon 凭证授权的 AdminSetUserPreference 用于设置 MFA 配置。

您也可以从 Amazon Cognito 控制台的用户菜单中设置用户 MFA 首选项。有关 Amazon Cognito 用户池 API 中的公共和机密身份验证模式的更多信息，请参阅了解 API、OIDC 和托管登录页面身份验证。

用户运行时的 MFA 逻辑详情

为确定用户登录时要采取的步骤，您的用户池会评估用户 MFA 首选项、用户属性、用户池 MFA 设置、威胁防护操作和自助账户恢复设置。然后，它会让用户登录，提示他们选择 MFA 方法、设置 MFA 方法或进行 MFA 验证。要设置 MFA 方法，用户必须提供电子邮件地址或电话号码或注册 TOTP 身份验证器。他们还可以设置 MFA 选项并提前注册首选项。下图列出了用户池配置对初始注册后立即登录尝试的详细影响。

此图所示的逻辑适用于基于 SDK 的应用程序和托管登录登录流程，但在托管登录中较不明显。当您排查 MFA 的问题时，应从用户遇到的结果出发，反向追溯到用户配置文件以及影响该结果的用户池配置。

便于最终用户选择 MFA 方法的 Amazon Cognito 用户池决策过程示意图。

以下清单对应于决策逻辑图中的编号，并详细描述了每个步骤。 checkmark 表示身份验证成功且流程已结束。 error 表示身份验证失败。

  1. 用户在登录界面输入其用户名，或用户名和密码。如果提供的凭证无效，其登录请求将被拒绝。

  2. 如果用户成功通过用户名密码身份验证，则需判断 MFA 是必需、可选还是关闭。如果关闭，则使用正确的用户名和密码即可成功进行身份验证。 Green circular icon with a checkmark symbol inside.

    1. 如果 MFA 为可选，需判断用户之前是否已设置 TOTP 身份验证器。如果已设置 TOTP，则提示用户进行 TOTP MFA。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

    2. 判断威胁防护的自适应身份验证功能是否已要求该用户设置 MFA。如果未分配 MFA，则用户可成功登录。 Green circular icon with a checkmark symbol inside.

  3. 如果 MFA 为必需，或自适应身份验证已为用户分配 MFA，则需判断该用户是否已启用并设定首选的 MFA 因素。如果有，则使用该因素提示用户进行 MFA 验证。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

  4. 如果用户尚未设置 MFA 首选项，则需判断该用户是否已注册 TOTP 身份验证器。

    1. 如果用户已注册 TOTP 身份验证器，则需判断该用户池中是否启用了 TOTP MFA（即使用户之前已设置身份验证器，此后 TOTP MFA 仍可能被禁用）。

    2. 判断用户池中电子邮件消息或短信形式的 MFA 是否也可用。

    3. 如果电子邮件和短信 MFA 均不可用，则提示用户进行 TOTP MFA 验证。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

    4. 如果电子邮件或短信 MFA 可用，则需判断用户是否具有相应的 email 或 phone_number 属性。如果已设置，则任何未被用作自助账户恢复的主要方式且已启用用于 MFA 的属性，均可供用户使用。

    5. 向用户发起一个 SELECT_MFA_TYPE 质询，其中 MFAS_CAN_SELECT 选项包含 TOTP 以及可用的短信或电子邮件 MFA 因素。

    6. 根据用户在 SELECT_MFA_TYPE 质询中选择的因素，提示用户完成该因素的验证。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

  5. 如果用户尚未注册 TOTP 身份验证器，或者已注册但 TOTP MFA 当前已禁用，则需判断该用户是否设置了 email 或 phone_number 属性。

  6. 如果用户仅有一个电子邮件地址或仅有一个电话号码，则需判断该属性是否同时也是用户池用于发送密码重置账户恢复消息的方式。如果是，则在 MFA 为必需的情况下，用户无法完成登录，Amazon Cognito 将返回错误。要使该用户成功登录，必须为其添加一个非恢复用途的属性，或为其注册一个 TOTP 身份验证器。

    1. 如果用户拥有可用的、非恢复用途的电子邮件地址或电话号码，则需判断对应的电子邮件或短信 MFA 因素是否已启用。

    2. 如果用户拥有非恢复用途的电子邮件地址属性，且电子邮件 MFA 已启用，则可向其发起 EMAIL_OTP 质询。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

    3. 如果用户拥有非恢复用途的电话号码属性，且短信 MFA 已启用，则可向其发起 SMS_MFA 质询。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

    4. 如果用户没有可用于已启用电子邮件或短信 MFA 因素的属性，则需判断 TOTP MFA 是否已启用。如果 TOTP MFA 已禁用，则在 MFA 为必需的情况下，用户无法完成登录，Amazon Cognito 将返回错误。要使该用户成功登录，必须为其添加一个非恢复用途的属性，或为其注册一个 TOTP 身份验证器。

      注意

      如果用户已注册 TOTP 身份验证器但 TOTP MFA 已禁用，则此步骤此前已被判定为否。

    5. 如果 TOTP MFA 已启用，则向用户发起一个 MFA_SETUP 质询，并在 MFAS_CAN_SETUP 选项中包含 SOFTWARE_TOKEN_MFA。要完成此质询，您必须单独为用户注册一个 TOTP 身份验证器，然后使用 "ChallengeName": "MFA_SETUP", "ChallengeResponses": {"USERNAME": "[username]", "SESSION": "[Session ID from VerifySoftwareToken]}" 进行回应。

    6. 用户使用来自 VerifySoftwareToken 请求的会话令牌响应 MFA_SETUP 质询后，向其发起 SOFTWARE_TOKEN_MFA 质询。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

  7. 如果用户同时拥有电子邮件地址和电话号码，则需判断其中哪一个属性（如果有的话）是密码重置账户恢复消息的主要发送方式。

    1. 如果自助账户恢复功能已禁用，则这两个属性均可用于 MFA。需判断电子邮件 MFA、短信 MFA 或两者是否已启用。

    2. 如果这两个属性均已启用为 MFA 因素，则向用户发起一个 SELECT_MFA_TYPE 质询，其中 MFAS_CAN_SELECT 选项为 SMS_MFA 和 EMAIL_OTP。

    3. 根据用户在 SELECT_MFA_TYPE 质询中选择的因素，提示他们完成该因素的验证。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

    4. 如果仅有一个属性符合 MFA 因素的条件，则向用户发起对应另一个因素的质询。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

      如果存在以下情形，可能会发生这种结果。

      1. 当用户同时拥有 email 和 phone_number 属性，短信和电子邮件 MFA 均已启用，且账户恢复的主要方式已设定为通过电子邮件或短信时。

      2. 当用户同时拥有 email 和 phone_number 属性，仅短信 MFA 或电子邮件 MFA 之一已启用，且自助账户恢复已禁用时。

  8. 如果用户尚未注册 TOTP 身份验证器，且既无 email 也无 phone_number 属性，则向其发起一个 MFA_SETUP 质询。MFAS_CAN_SETUP 列表中包含用户池中所有已启用且不是账户恢复主要选项的 MFA 因素。用户可通过 ChallengeResponses 响应此质询，以设置电子邮件或 TOTP MFA。要设置短信 MFA，必须先单独为用户添加电话号码属性，然后重新开始身份验证流程。

    对于 TOTP MFA，使用 "ChallengeName": "MFA_SETUP", "ChallengeResponses": {"USERNAME": "[username]", "SESSION": "[Session ID from VerifySoftwareToken]"} 进行响应。

    对于电子邮件 MFA，使用 "ChallengeName": "MFA_SETUP", "ChallengeResponses": {"USERNAME": "[username]", "email": "[user's email address]"} 进行响应。

    1. 根据用户在 SELECT_MFA_TYPE 质询中选择的因素，提示他们完成该因素的验证。如果用户成功响应该 MFA 质询，即可成功登录。 Green circular icon with a checkmark symbol inside.

为用户池配置多重身份验证

您可以在 Amazon Cognito 控制台中配置 MFA，也可以使用 SetUserPoolMfaConfig API 操作和 SDK 方法进行配置。

在 Amazon Cognito 控制台中配置 MFA

  1. 登录 Amazon Cognito 控制台。

  2. 选择用户池。

  3. 从列表中选择一个现有用户池，或创建一个用户池。

  4. 选择登录菜单。找到多重身份验证，然后选择编辑。

  5. 选择您希望用于用户池的MFA 强制执行方法。

    一张来自 Amazon Cognito 控制台的屏幕截图，显示了 MFA 选项。

    1. 需要 MFA。用户池中的所有用户必须使用额外的短信验证码、电子邮件验证码或基于时间的一次性密码（TOTP）验证码作为额外的身份验证因素进行登录。

    2. 可选 MFA。您可以为用户提供选项来注册额外的登录安全因素，但仍允许未配置 MFA 的用户登录。如果您使用自适应身份验证，请选择此选项。有关自适应身份验证的更多信息，请参阅具备威胁防护的高级安全功能。

    3. 无 MFA。您的用户无法注册其他登录安全要素。

  6. 选择您在应用程序中支持的 MFA 方法。您可以将电子邮件消息、短信或 TOTP 生成的身份验证器应用程序设置为第二个因素。

  7. 如果使用 SMS 文本消息作为第二安全要素，并且没有配置 IAM 角色与 Amazon Simple Notification Service（Amazon SNS）一起使用 SMS 消息，您可以在控制台中创建一个角色。在用户池的身份验证方法菜单中，找到短信，然后选择编辑。您还可以使用允许 Amazon Cognito 代表您向用户发送短信的现有角色。有关更多信息，请参阅 IAM 角色。

    如果使用电子邮件消息作为第二安全因素，但尚未为 Amazon Simple Email Service (Amazon SES) 配置源身份以发送电子邮件消息，则可以在控制台中创建一个。必须选择使用 SES 发送电子邮件选项。在用户池的身份验证方法菜单中，找到电子邮件，然后选择编辑。从列表中可用的已验证身份中，选择一个发件人电子邮件地址。如果您选择了一个已验证的域（例如 example.com），则还必须在该已验证域下配置一个发件人姓名，例如 admin-noreply@example.com。

  8. 选择保存更改。