使用 Amazon Cognito 用户池 API 和用户池端点 - Amazon Cognito
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

使用 Amazon Cognito 用户池 API 和用户池端点

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

  1. 您的用户池端点包括托管 UI联合身份验证端点。它们构成了一个公共网页包,当您为用户池选择域时,Amazon Cognito 会激活这些网页。要快速开始使用 Amazon Cognito 用户池的身份验证和授权功能,包括注册、登录、密码管理和多重身份验证(MFA)页面,请使用托管 UI 的内置用户界面。其他用户池端点便于使用第三方身份提供者(IdP)进行身份验证。他们执行的服务包括以下各项。

    1. 服务提供者回调端点,用于处理来自您的 IdP 的经身份验证的声明,例如 saml2/idpresponseoauth2/idpresponse。当 Amazon Cognito 是您的应用程序和 IdP 之间的中间服务提供者(SP)时,回调端点代表服务。

    2. 提供有关您的环境的信息的端点,例如 oauth2/userInfojwks.json。您的应用程序在使用 Amazon SDK 和 OAuth 2.0 库验证令牌或检索用户配置文件数据时使用这些端点。

  2. Amazon Cognito 用户池 API 是一组用于您的 Web 或移动应用程序的工具,它在您自己的自定义前端中收集登录信息,以验证用户身份。用户池 API 身份验证生成以下 JSON Web 令牌。

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

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

      注意

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

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

Amazon Cognito 用户池 API 有双重用途。它创建和配置您的 Amazon Cognito 用户池资源。例如,您可以创建用户池、添加 Amazon Lambda 触发器以及配置您的托管 UI 域。用户池 API 还为本地用户和关联的用户执行注册、登录和其他用户操作。

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

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

  2. 您的应用程序发送了 SignUp API 请求,并在用户池中创建新用户。

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

  4. 您的应用程序发送带有用户确认码的 ConfirmSignUp API 请求。

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

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

在 Amazon Cognito 用户池 API 中,您无法登录通过 IdP 进行联合身份验证的用户。您必须通过用户池端点对这些用户进行身份验证。有关包含托管 UI 的用户池端点的信息,请参阅用户池联合身份验证端点和托管 UI 参考。联合用户可以在托管 UI 中开始登录并选择其 IdP,您也可以跳过托管 UI,将用户直接发送到您的 IdP 以进行登录。当您的 API 发送请求到 对端点授权 且带有 IdP 参数时,Amazon Cognito 会以静默方式将用户重定向到 IdP 登录页面。

用户池端点示例场景

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

  2. 您可以向用户提供您注册开发人员凭证的社交身份提供者列表。您的用户选择了 Apple。

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

  4. 用户的浏览器打开 Apple OAuth 授权页面。用户选择允许 Amazon Cognito 读取其个人资料信息。

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

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

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

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

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

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

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

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

例如,要在 UpdateUserPool API 请求中修改您的用户池,您必须提供 Amazon 凭证和 IAM 权限才能更新资源。

要在 Amazon Command Line Interface(Amazon CLI)或 Amazon SDK 中授权这些请求,请使用将 IAM 凭证添加到请求的环境变量或客户端配置来配置您的环境。有关更多信息,请参阅《Amazon Web Services 一般参考》中的使用 Amazon 凭证访问 Amazon。对于 Amazon Cognito 用户池 API,您也可以直接向服务端点发送请求。您必须使用嵌入到请求标头中的 Amazon 凭证授权或签署 这些请求。有关更多信息,请参阅签署 Amazon 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 资源的特权访问权限。要在应用程序中注册用户,您的服务器可以在 AdminCreateUser API 请求中包含 Amazon。有关 OAuth 客户端类型的更多信息,请参阅 OAuth 2.0 授权框架中的客户端类型

要在 Amazon CLI 或 Amazon SDK 中授权这些请求,请使用将 IAM 凭证添加到请求的环境变量或客户端配置来配置服务器端应用程序的环境。有关更多信息,请参阅《Amazon Web Services 一般参考》中的使用 Amazon 凭证访问 Amazon。对于 Amazon Cognito 用户池 API,您也可以直接向服务端点发送请求。您必须使用嵌入到请求标头中的 Amazon 凭证授权或签署 这些请求。有关更多信息,请参阅签署 Amazon 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 注册此用户。

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

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

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

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

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

要在使用 Amazon SDK 开发的公共客户端中发送这些请求,您无需配置任何凭证。在您的请求中包含 AccessTokenSession 参数。对于 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 获取刷新令牌作为参数。刷新令牌用作授权令牌和目标资源。