API 和 SDK 身份验证的授权模型 - Amazon Cognito
服务器端身份验证选项客户端身份验证选项使用 API 和端点

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

API 和 SDK 身份验证的授权模型

当你开始使用用户池身份验证时，你必须决定你的应用程序授权模式。Amazon Cognito 身份验证通常要求您按顺序实现两个 API 操作。用于身份验证的 API 操作取决于您的应用程序的特性。将应用程序分发给用户的公共客户端使用公共身份验证，而登录请求不需要授权。服务器端客户端（应用程序逻辑托管在远程系统上）可以通过登录请求的 IAM 授权来保护身份验证操作。以下 API 操作对及其相应的 SDK 方法映射到每种可用的授权模型。

要比较 API 身份验证并查看 API 操作及其授权模型的完整列表，请参阅了解 API、OIDC 和托管登录页面身份验证。

Client-side (public) authentication

  1. InitiateAuth

  2. RespondToAuthChallenge

InitiateAuthRespondToAuthChallenge并且未经身份验证 APIs ，无法与客户端公共应用程序客户端一起使用。有关更多信息，请参阅客户端身份验证选项 和了解 API、OIDC 和托管登录页面身份验证。

Server-side authentication

  1. AdminInitiateAuth

  2. AdminRespondToAuthChallenge

AdminInitiateAuth 和 AdminRespondToAuthChallenge 需要 IAM 凭证，适用于服务器端机密应用程序客户端。有关更多信息，请参阅服务器端身份验证选项 和了解 API、OIDC 和托管登录页面身份验证。

用户通过应答连续的质询进行身份验证，直到身份验证失败或 Amazon Cognito 向用户发放令牌。您可以在包含不同质询的流程中对 Amazon Cognito 重复这些步骤，以支持任何自定义身份验证流程。

服务器端身份验证选项

Web 应用程序和其他服务器端应用程序在远程服务器上的会话中实现身份验证，通常是在启动与该服务器会话的浏览器中。服务器端应用程序通常具有以下特征。

  • 它们是在服务器上安装的 Java、Ruby 或 Node.js 等语言的应用程序中构建的。

  • 它们连接到可能有客户端密钥的用户池应用程序客户端，称为机密客户端。

  • 他们有权访问 AWS 证书。

  • 他们调用托管登录进行身份验证，或者在用户池 API 中使用 IAM 授权的操作和 SD AWS K。

  • 他们为内部客户提供服务，也可能为公共客户提供服务。

使用用户池 API 的服务器端操作可以使用密码、一次性密码或密钥作为主要登录因素。对于服务器端应用程序，用户池身份验证与客户端应用程序的身份验证类似，但以下情况除外：

  • 服务器端应用程序发出 AdminInitiateAuthAPI 请求。此操作需要具有包含cognito-idp:AdminInitiateAuth和权限的 AWS 证书cognito-idp:AdminRespondToAuthChallenge。该操作返回所需的质询或身份验证结果。

  • 当应用程序收到质询时，它会发出 AdminRespondToAuthChallengeAPI 请求。AdminRespondToAuthChallengeAPI 操作还需要 AWS 凭证。

有关使用 AWS 凭证签署 Amazon Cognito API 请求的更多信息，请参阅AWS 一般参考中的签名版本 4 签名流程。

在 AdminInitiateAuth 响应 ChallengeParameters 中，USER_ID_FOR_SRP 属性（如果存在）包含用户的实际用户名而不是别名（如电子邮件地址或电话号码）。在 AdminRespondToAuthChallenge 调用的 ChallengeResponses 中，您必须在 USERNAME 参数中传递此用户名。

注意

由于后端管理员实现使用管理员身份验证流程，因此该流程不支持记住的设备。在您启用设备跟踪时，管理员身份验证成功，但任何对刷新访问令牌的调用均会失败。

客户端身份验证选项

安装在用户设备上的移动应用程序和其他客户端应用程序类型通常具有以下特征。

  • 它们采用 React native、Flutter 和 Swift 等语言构建，并部署到用户设备上。

  • 它们连接到没有客户端密钥的用户池应用程序客户端，称为公共客户端。

  • 他们无法访问授权 IAM 授权的 API 请求的 AWS 证书。

  • 他们调用托管登录进行身份验证，或者使用 SDK 在用户池 API 中使用公开和令牌授权的操作。 AWS

  • 他们为公众客户提供服务，并允许任何人注册和登录。

使用用户池 API 的客户端操作可以使用密码、一次性密码或密钥作为主要登录因素。以下过程适用于您使用AWS Amplify或创建的用户客户端应用程序。AWS SDKs

  1. 用户将他们的用户名和密码输入到应用程序中。

  2. 应用程序使用用户的用户名和安全远程密码（SRP）详细信息调用 InitiateAuth 操作。

    此 API 操作返回身份验证参数。

    注意

    该应用程序使用内置的 Amazon Cognito SRP 功能生成 SRP 详细信息。 AWS SDKs

  3. 应用程序调用 RespondToAuthChallenge 操作。如果调用成功，则 Amazon Cognito 返回用户的令牌，并且身份验证流程完成。

    如果 Amazon Cognito 需要另一个质询，则对 RespondToAuthChallenge 的调用不返回任何令牌。相反，调用会返回一个会话。

  4. 如果 RespondToAuthChallenge 返回一个会话，应用程序将再次调用 RespondToAuthChallenge，这次使用会话和质询响应（例如，MFA 代码）。

了解 API、OIDC 和托管登录页面身份验证

Amazon Cognito 用户池是多种身份验证技术的组合。他们是外部身份提供商 (IdPs) 的依赖方。它们 IdPs 适用于使用 OpenID Connect (OIDC) 实现身份验证的应用程序。 SDKs它们作为 JSON Web 令牌 (JWTs) 的发行者提供身份验证，类似于 OIDC 身份验证，但使用的是其中的一部分 API 方法。 AWS SDKs它们也可以是应用程序的安全入口点。

当您想要注册、登录和管理用户池中的用户时，有两种选择。

  1. 您的托管登录页面和经典托管用户界面包括托管登录用户交互式端点以及处理 IdP 和 r elying-party 角色的联合终端节点。它们构成了一个公共网页包，当您为用户池选择域时，Amazon Cognito 会激活这些网页。要快速开始使用 Amazon Cognito 用户池的身份验证和授权功能，包括注册、登录、密码管理和多重身份验证 (MFA) 页面，请使用托管登录的内置用户界面。

    其他用户池端点便于使用第三方身份提供商进行身份验证（IdPs）。他们执行的服务包括以下各项。

    1. 服务提供商回调终端节点，用于来自您的经过身份验证的声明 IdPs，比如saml2/idpresponse和。oauth2/idpresponse当 Amazon Cognito 是您的应用程序和 IdP 之间的中间服务提供者（SP）时，回调端点代表服务。

    2. 提供有关您的环境的信息的端点，例如 oauth2/userInfo 和 /.well-known/jwks.json。您的应用在使用 OIDC 或 2.0 开发者库验证令牌或检索用户个人资料数据时会使用这些端点。 OAuth

  2. Amazon Cognito 用户池 API 是一组工具，供您的网络或移动应用程序在您自己的自定义前端收集登录信息后对用户进行身份验证。用户池 API 身份验证生成以下 JSON Web 令牌。

    1. 带有来自您的用户的可验证属性声明的身份令牌。

    2. 一种访问令牌，用于授权用户针对 AWS 服务端点创建经令牌授权的 API 请求。

      注意

      默认情况下，来自用户池 API 身份验证的访问令牌仅包含 aws.cognito.signin.user.admin 作用域。要生成具有额外作用域的访问令牌（例如，授权对第三方 API 的请求），请在通过用户池端点进行身份验证期间请求作用域，或者在 令牌生成前 Lambda 触发器 中添加自定义作用域。自定义访问令牌会增加您的 AWS 账单费用。

    3. 一种刷新令牌，用于授权请求新 ID 和访问令牌，并刷新用户身份和访问控制属性。

您可以将通常通过用户池端点登录的联合用户与其配置文件位于用户池本地 的用户相关联。本地用户仅存在于您的用户池目录中，无需通过外部 IdP 进行联合身份验证。如果您在 AdminLinkProviderForUserAPI 请求中将他们的联合身份关联到本地用户，则他们可以使用用户池 API 登录。有关更多信息，请参阅 将联合用户与现有用户配置文件关联。

Amazon Cognito 用户池 API 有双重用途。

  1. 它创建和配置您的 Amazon Cognito 用户池资源。例如，您可以创建用户池、添加 AWS Lambda 触发器以及配置托管您的托管登录页面的用户池域。

  2. 它为本地用户和关联用户执行注册、登录和其他用户操作。

使用 Amazon Cognito 用户池 API 的示例场景

  1. 用户选择了您在应用程序中创建的“创建账户”按钮。他们输入电子邮件地址和密码。

  2. 您的应用程序发送 SignUpAPI 请求并在您的用户池中创建了一个新用户。

  3. 应用程序提示用户输入电子邮件确认代码。用户输入他们在电子邮件中收到的代码。

  4. 您的应用会发送包含用户确认码的 ConfirmSignUpAPI 请求。

  5. 应用程序提示您的用户输入用户名和密码，而用户输入其信息。

  6. 您的应用程序发送 InitiateAuthAPI 请求并存储 ID 令牌、访问令牌和刷新令牌。应用程序调用 OIDC 库来管理用户的令牌并为该用户维护持久会话。

在 Amazon Cognito 用户池 API 中，您无法登录通过 IdP 进行联合身份验证的用户。您必须通过用户池端点对这些用户进行身份验证。有关包含托管登录的用户池终端节点的更多信息，请参阅用户池端点和托管登录参考。

您的联合用户可以从托管登录开始并选择他们的 IdP，也可以跳过托管登录，将您的用户直接发送到您的 IdP 进行登录。当您的 API 发送请求到 对端点授权 且带有 IdP 参数时，Amazon Cognito 会以静默方式将用户重定向到 IdP 登录页面。

托管登录页面的示例场景

  1. 用户选择了您在应用程序中创建的“创建账户”按钮。

  2. 托管登录会向您的用户显示您在其中注册开发者凭证的社交身份提供商的列表。您的用户选择了 Apple。

  3. 您的应用程序向 对端点授权 发出请求，提供者名称为 SignInWithApple。

  4. 用户的浏览器会打开 Apple 身份验证页面。您的用户登录并选择授权 Amazon Cognito 阅读他们的个人资料信息。

  5. Amazon Cognito 确认 Apple 访问令牌并查询用户的 Apple 个人资料。

  6. 用户向您的应用程序出示 Amazon Cognito 授权代码。

  7. 应用程序中的 OIDC 库与交换授权码，令牌端点并存储用户池发布的 ID 令牌、访问令牌和刷新令牌。您的应用程序使用 OIDC 库来管理用户的令牌并为该用户维护持续会话。

用户池 API 和托管登录页面支持本指南中描述的各种场景。以下部分探讨了用户池 API 如何进一步划分为支持您的注册、登录和资源管理要求的类。

Amazon Cognito 用户池经过身份验证和未经身份验证的 API 操作

Amazon Cognito 用户池 API 既是资源管理接口，也是面向用户的身份验证和授权接口，结合了其操作中遵循的授权模型。根据 API 操作，您可能需要使用 IAM 凭证、访问令牌、会话令牌、客户端密钥或者前面这些内容的组合提供授权。对于许多用户身份验证和授权操作，您可以选择请求的经过身份验证和未经身份验证的版本。对于分发给用户的应用程序（例如移动应用程序），最佳安全实践是提供未经身份验证的操作；您无需在代码中包含任何密钥。

您只能在 IAM policy 中为 经过 IAM 身份验证的管理操作 和 经过 IAM 身份验证的用户操作 分配权限。

经过 IAM 身份验证的管理操作会修改和查看您的用户池和应用程序客户端配置，就像您在 AWS Management Console中所做的那样。

例如，要在 UpdateUserPoolAPI 请求中修改您的用户池，您必须出示 AWS 证书和 IAM 权限才能更新资源。

要在 AWS Command Line Interface (AWS CLI) 或 AWS 软件开发工具包中授权这些请求，请使用环境变量或向请求添加 IAM 证书的客户端配置来配置您的环境。有关更多信息，请参阅中的AWS 使用您的 AWS 凭证进行访问AWS 一般参考。对于 Amazon Cognito 用户池 API，您也可以直接向服务端点发送请求。您必须使用在请求标题中嵌入的 AWS 凭据对这些请求进行授权或签名。有关更多信息，请参阅签署 AWS API 请求。

经过 IAM 身份验证的管理操作
AddCustomAttributes
CreateGroup
CreateIdentityProvider
CreateResourceServer
CreateUserImportJob
CreateUserPool
CreateUserPoolClient
CreateUserPoolDomain
DeleteGroup
DeleteIdentityProvider
DeleteResourceServer
DeleteUserPool
DeleteUserPoolClient
DeleteUserPoolDomain
DescribeIdentityProvider
DescribeResourceServer
DescribeRiskConfiguration
DescribeUserImportJob
DescribeUserPool
DescribeUserPoolClient
DescribeUserPoolDomain
GetCSVHeader
GetGroup
GetIdentityProviderByIdentifier
GetSigningCertificate
GetUICustomization
GetUserPoolMfaConfig
ListGroups
ListIdentityProviders
ListResourceServers
ListTagsForResource
ListUserImportJobs
ListUserPoolClients
ListUserPools
ListUsers
ListUsersInGroup
SetRiskConfiguration
SetUICustomization
SetUserPoolMfaConfig
StartUserImportJob
StopUserImportJob
TagResource
UntagResource
UpdateGroup
UpdateIdentityProvider
UpdateResourceServer
UpdateUserPool
UpdateUserPoolClient
UpdateUserPoolDomain

经过 IAM 身份验证的用户操作注册、登录、管理凭证、修改和查看您的用户。

例如，您可以有一个服务器端应用程序层，为 Web 前端提供支持。您的服务器端应用程序是您信任的 OAuth 机密客户端，可以访问您的 Amazon Cognito 资源。要在应用程序中注册用户，您的服务器可以在 AdminCreateUserAPI 请求中包含 AWS 凭据。有关 OAuth 客户端类型的更多信息，请参阅 OAuth 2.0 授权框架中的客户端类型。

要在 AWS CLI 或 AWS SDK 中授权这些请求，请使用环境变量或向请求添加 IAM 证书的客户端配置来配置服务器端应用程序环境。有关更多信息，请参阅中的AWS 使用您的 AWS 凭证进行访问AWS 一般参考。对于 Amazon Cognito 用户池 API，您也可以直接向服务端点发送请求。您必须使用在请求标题中嵌入的 AWS 凭据对这些请求进行授权或签名。有关更多信息，请参阅签署 AWS API 请求。

如果您的应用程序客户端有客户端密钥，则您必须提供 IAM 凭证，并在 AuthParameters 中提供 SecretHash 参数或 SECRET_HASH 值（取决于操作）。有关更多信息，请参阅 计算密钥哈希值。

经过 IAM 身份验证的用户操作
AdminAddUserToGroup
AdminConfirmSignUp
AdminCreateUser
AdminDeleteUser
AdminDeleteUserAttributes
AdminDisableProviderForUser
AdminDisableUser
AdminEnableUser
AdminForgetDevice
AdminGetDevice
AdminGetUser
AdminInitiateAuth
AdminLinkProviderForUser
AdminListDevices
AdminListGroupsForUser
AdminListUserAuthEvents
AdminRemoveUserFromGroup
AdminResetUserPassword
AdminRespondToAuthChallenge
AdminSetUserMFAPreference
AdminSetUserPassword
AdminSetUserSettings
AdminUpdateAuthEventFeedback
AdminUpdateDeviceStatus
AdminUpdateUserAttributes
AdminUserGlobalSignOut

未经身份验证的用户操作注册、登录以及为您的用户启动密码重置。当您希望 Internet 上的任何人都可以注册并登录您的应用程序时，请使用未经身份验证（公开）的 API 操作。

例如，要在您的应用程序中注册用户，您可以分发一个不提供任何密钥特权访问权限的 OAuth 公共客户端。您可以使用未经身份验证的 API 操作SignUp注册此用户。

要在使用 AWS SDK 开发的公共客户端中发送这些请求，您无需配置任何凭据。对于没有额外授权的 Amazon Cognito 用户池 API，您也可以直接向服务端点发送请求。

如果您的应用程序客户端有客户端密钥，则您必须在 AuthParameters 中提供 SecretHash 参数或 SECRET_HASH 值（取决于操作）。有关更多信息，请参阅 计算密钥哈希值。

未经身份验证的用户操作
SignUp
ConfirmSignUp
ResendConfirmationCode
ForgotPassword
ConfirmForgotPassword
InitiateAuth

经过令牌授权的用户操作在用户已登录或开始登录流程之后，注销、管理其凭证、修改和查看用户。如果您不想在应用程序中分发密钥，并且想要使用用户自己的凭证授权请求，请使用经过令牌授权的 API 操作。如果用户已完成登录，则您必须使用访问令牌来授权其经过令牌授权的 API 请求。如果您的用户正在登录流程中，则您必须使用 Amazon Cognito 在对先前请求的响应中返回的会话令牌，授权其经过令牌授权的 API 请求。

例如，在公共客户端中，您可能希望更新用户的配置文件，限制用户仅对自己的配置文件具有写入权限。要进行此更新，您的客户端可以在 UpdateUserAttributesAPI 请求中包含用户的访问令牌。

要在使用 AWS SDK 开发的公共客户端中发送这些请求，您无需配置任何凭据。在您的请求中包含 AccessToken 或 Session 参数。对于 Amazon Cognito 用户池 API，您也可以直接向服务端点发送请求。要向服务端点授权请求，请在请求的 POST 正文中包含访问令牌或会话令牌。

要签署经过令牌授权的操作的 API 请求，请将访问令牌作为 Authorization 标头包含在请求中，格式为 Bearer <Base64-encoded access token>。

经过令牌授权的用户操作 AccessToken 会话
RespondToAuthChallenge ✓
ChangePassword ✓
GetUser ✓
UpdateUserAttributes ✓
DeleteUserAttributes ✓
DeleteUser ✓
ConfirmDevice ✓
ForgetDevice ✓
GetDevice ✓
ListDevices ✓
UpdateDeviceStatus ✓
GetUserAttributeVerificationCode ✓
VerifyUserAttribute ✓
SetUserSettings ✓
SetUserMFAPreference ✓
GlobalSignOut ✓
AssociateSoftwareToken ✓ ✓
UpdateAuthEventFeedback ✓
VerifySoftwareToken ✓ ✓
RevokeToken¹

¹ RevokeToken 将刷新令牌作为参数。刷新令牌用作授权令牌和目标资源。