View a markdown version of this page

在中管理身份验证方法 Amazon 软件开发工具包 - Amazon Cognito
Choice-based authenticationClient-based authenticationStep-up 使用 USER_AUTH 流程进行身份验证
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

在中管理身份验证方法 Amazon 软件开发工具包

Amazon Cognito 用户池中的用户可以通过多种初始登录选项（也称为因素）进行登录。对于某些因素，用户还可以继续完成多重身份验证（MFA）。这些第一重因素包括用户名和密码、一次性密码、通行密钥以及自定义身份验证。有关更多信息，请参阅 身份验证流程。当您的应用程序具有内置 UI 组件并导入 S Amazon DK 模块时，您必须构建用于身份验证的应用程序逻辑。此时，您必须从两种主要方法中选择其一，并通过此方法确定要实现的身份验证机制。

您可以实现基于客户端的身份验证，即由您的应用程序（或客户端）在一开始就声明所使用的身份验证类型。另一种选择是基于选择的身份验证，即您的应用程序先收集用户名，然后请求该用户可用的身份验证类型。您可以根据需求，在同一个应用程序中同时实现这两种模式，或在不同的应用程序客户端之间分别使用。每种方法都有其独有的功能，例如：基于客户端的身份验证支持自定义身份验证，而基于选择的身份验证则支持无密码身份验证。

在使用用户池 API 的 Amazon SDK 实现进行身份验证的自定义应用程序中，您的 API 请求结构必须与用户池配置、应用程序客户端配置和客户端首选项保持一致。如果 InitiateAuth 会话以 AuthFlow 值为 USER_AUTH 开始，则启动基于选择的身份验证。Amazon Cognito 会在 API 响应中返回一个质询，内容为用户的首选身份验证方法或可用选项列表。如果会话以 AuthFlow 值为 CUSTOM_AUTH 开始，则直接进入基于 Lambda 触发器的自定义身份验证流程。

有些身份验证方法固定为两种流程中的一种，有些方法在两种流程中都可用。

Choice-based authentication

您的应用程序可以在基于选择的身份验证中请求以下身份验证方法。在InitiateAuth或的PREFERRED_CHALLENGE参数中声明这些选项 AdminInitiateAuth，或者在RespondToAuthChallenge或的ChallengeName参数中声明这些选项AdminRespondToAuthChallenge。

重要

Choice-based 登录有两个先决条件。您的应用程序客户端必须激活ALLOW_USER_AUTH身份验证流程，并且无密码和密钥方法（、EMAIL_OTPSMS_OTP、WEB_AUTHN）需要在 Ess en tial s 或 Plus 功能计划中使用用户池，而这些方法在 Lite 层中不可用。 PASSWORD（包括 SRP）适用于所有功能计划。如果您的用户没有看到基于选择的方法，请先确认应用程序-客户端流程和功能计划，然后再进一步进行故障排除。

  1. EMAIL_OTP 和 SMS_OTP

    使用一次性密码进行无密码登录

  2. WEB_AUTHN

    使用密钥进行无密码登录 WebAuthn

  3. PASSWORD

    Sign-in 使用永久密码

    Sign-in 使用永久密码和安全有效载荷

    登录后进行 MFA

要在其 API 上下文中查看这些选项，请参阅ChallengeName中的RespondToAuthChallenge。

Choice-based 登录会根据您的初始请求发出质询。该质询要么验证所请求的选项是否可用，要么提供一份可用选项列表。您的应用程序可将这些选项显示给用户，用户随后输入其首选登录方式的凭证，并通过响应质询继续完成身份验证。

您的身份验证流程中有以下基于选择的选项。此类请求均要求您的应用程序首先收集用户名，或从缓存中获取用户名。

  1. 仅使用 USERNAME 作为 AuthParameters 来请求选项。Amazon Cognito 返回 SELECT_CHALLENGE 质询。随后，您的应用程序可以提示用户选择一种质询方式，并将该选择作为响应返回给用户池。

  2. 通过在 PREFERRED_CHALLENGE 的 AuthParameters 以及您首选质询（如有）的参数来请求一个首选质询。例如，如果您请求的 PREFERRED_CHALLENGE 为 PASSWORD_SRP，则还必须包含 SRP_A。如果您的用户、用户池和应用程序客户端都针对首选挑战进行了配置，则 Amazon Cognito 会以该挑战的下一步作为响应，例如PASSWORD_VERIFIER在PASSWORD_SRP流程中或EMAIL_OTP和SMS_OTP流程CodeDeliveryDetails中。如果首选质询不可用，Amazon Cognito 将返回 SELECT_CHALLENGE，并附带一份可用质询列表。

  3. 首先让用户登录，然后再请求其基于选择的身份验证选项。使用已登录用户的访问令牌的GetUserAuthFactors请求会返回他们可用的基于选择的身份验证因素和 MFA 设置。通过此身份验证选项，用户可先使用用户名和密码登录，随后启用其他形式的身份验证。您也可以使用此操作，为已通过首选质询完成登录的用户检查其他可用选项。

要为应用程序客户端配置基于选择的身份验证，请在允许的身份验证流程中添加 ALLOW_USER_AUTH。您还必须在用户池配置中选择要允许的基于选择的身份验证因素。以下流程说明了如何选择基于选择的身份验证因素。

Amazon Cognito console
在用户池中配置基于选择的身份验证选项

  1. 登录 Amazon 并导航到 Amazon Cognito 用户池控制台。选择一个用户池或新建一个。

  2. 在您的用户池配置中，选择Sign-in菜单。找到基于选择的登录选项，然后选择编辑。

  3. 密码选项始终可用。这包括 PASSWORD 和 PASSWORD_SRP 流程。选择要添加到用户选项中的其他选项。您可以为 WEB_AUTHN 添加通行密钥，为 EMAIL_OTP 添加电子邮件消息一次性密码，为 SMS_OTP 添加 SMS 消息一次性密码。

  4. 选择保存更改。

API/SDK

以下部分CreateUserPool或UpdateUserPool请求正文配置了基于选择的身份验证的所有可用选项。

"Policies": {
    "SignInPolicy": {
        "AllowedFirstAuthFactors": [
            "PASSWORD",
            "WEB_AUTHN",
            "EMAIL_OTP",
            "SMS_OTP"
        ]
    }
},

Client-based authentication

Client-based 身份验证支持以下身份验证流程。在InitiateAuth或的AuthFlow参数中声明这些选项AdminInitiateAuth。

  1. USER_PASSWORD_AUTH 和 ADMIN_USER_PASSWORD_AUTH

    Sign-in 使用永久密码

    登录后进行 MFA

    此身份验证流程在基于选择的身份验证中等同于 PASSWORD。

  2. USER_SRP_AUTH

    Sign-in 使用永久密码和安全有效载荷

    登录后进行 MFA

    此身份验证流程在基于选择的身份验证中等同于 PASSWORD_SRP。

  3. REFRESH_TOKEN_AUTH

    刷新令牌

    此身份验证流程仅在基于客户端的身份验证中可用。

  4. CUSTOM_AUTH

    自定义身份验证

    此身份验证流程仅在基于客户端的身份验证中可用。

对于基于客户端的身份验证，Amazon Cognito 假设您已在用户开始身份验证流程之前确定了其希望使用的身份验证方式。确定用户要提供的登录因素的逻辑必须通过默认设置或自定义提示来确定，然后在首次向用户池发起的请求中声明。InitiateAuth 请求需声明一个与所列选项之一直接对应的登录 AuthFlow，例如 USER_SRP_AUTH。通过该声明，该请求还包含启动身份验证所需的参数，例如 USERNAME、SECRET_HASH 和 SRP_A。Amazon Cognito 可能会在该请求之后返回额外的质询，例如针对 SRP 的 PASSWORD_VERIFIER，或针对使用 TOTP MFA 的密码登录的 SOFTWARE_TOKEN_MFA。

要为应用程序客户端配置基于客户端的身份验证，请在允许的身份验证流程中添加 ALLOW_USER_AUTH 之外的任何身份验证流程。示例包括 ALLOW_USER_PASSWORD_AUTH、ALLOW_CUSTOM_AUTH、ALLOW_REFRESH_TOKEN_AUTH。允许基于客户端的身份验证流程无需额外的用户池配置。

Step-up 使用 USER_AUTH 流程进行身份验证

您可以使用InitiateAuth和RespondToAuthChallenge操作在现有USER_AUTH流程中请求升级身份验证。没有新的 API 操作。相应的服务器端操作AdminInitiateAuth和AdminRespondToAuthChallenge支持相同的升压参数和行为，AdminInitiateAuth也可以选择使用访问令牌。当用户拥有现有 ID 令牌时，以及当用户首次向目标级别进行身份验证时，此流程都会起作用。有关流程的更多信息，请参阅身份验证会话示例。

有关 ACR 级别和 AMR 值的更多信息，请参阅ACR 和 AMR 声明的身份验证级别。

注意

Step-up 身份验证需要 Essentials 或 Plus 功能计划。

您可以在InitiateAuth（或AdminInitiateAuth）请求的AuthParameters映射中传递升级参数：新的TARGET_ACR_VALUES和以及MAX_AGE现有的USERNAMEACCESS_TOKEN、和PREFERRED_CHALLENGE。有关每个参数的定义和限制，请参阅 Amazon Cognito 用户池 API 参考AdminInitiateAuth中的InitiateAuth和。

下表描述了 Amazon Cognito 如何响应这些参数的组合。

USER_AUTH 升级身份验证行为
参数 行为
TARGET_ACR_VALUES而且ACCESS_TOKEN，MAX_AGE很满意 Amazon Cognito 将用户从令牌的当前因素提升到最高优先级的可满足级别。
TARGET_ACR_VALUES而且ACCESS_TOKEN，MAX_AGE不满意 Amazon Cognito 会从头开始向目标级别对用户进行身份验证。
TARGET_ACR_VALUES没有 ACCESS_TOKEN Amazon Cognito 会从头开始向目标级别对用户进行身份验证。
两个参数都没有 该USER_AUTH流程的行为方式与未进行升级身份验证时的行为相同。

在设计升级身份验证流程时，请记住以下行为。

  • Step-up 身份验证要么全有要么全无。如果达到目标等级需要多个挑战，例如密码和第 4 级的 TOTP，而用户未通过任何挑战，则升级尝试将完全失败。亚马逊 Cognito 不发行中间代币。

  • 如果提供的令牌已经达到或超过请求的级别，Amazon Cognito 将返回错误而不是发行新令牌。这可以防止应用程序使用升级身份验证作为令牌刷新机制。

  • 用户必须已经具备满足所请求级别的因子。如果用户没有配置任何因子来满足任何请求的目标级别，Amazon Cognito 将返回错误。 Step-up身份验证不会提示用户设置新因子。

  • MFA 是一个底线。如果用户或用户池的 MFA 设置需要 MFA，则即使目标级别较低且不需要 MFA，初始登录仍会强制执行并提示进行 MFA 质询。威胁防护（高级安全功能）提示的 MFA 也会在初始登录时强制执行，即使请求的目标 ACR 级别本来不需要使用 MFA 也是如此。 TARGET_ACR_VALUES无法抑制所需的 MFA 提示。目标最多可以影响 Amazon Cognito 提示的几个已启用 MFA 因素中的哪一个。如果升级请求针对的是需要使用 MFA 的用户的较低级别（例如级别 1），则 Amazon Cognito 会以静默方式强制执行所需的 MFA。它会让用户向上移动，并且不会返回错误。

使用请求升级身份验证TARGET_ACR_VALUES需要 Essentials 或 Plus 功能计划。有关更多信息，请参阅 功能计划要求。