Amazon Cognito
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

用户池应用程序集成和联合入门

Amazon Cognito 用户池应用程序集成和联合提供了登录用户的可定制体验以及与 Facebook、Google 和 Login with Amazon 以及 SAML 2.0 身份提供商的集成。使用 Amazon Cognito 开发工具包和几行代码,您就可以向移动或 Web 应用程序添加注册和登录页。通过这些新功能,Amazon Cognito 用户池可以对以下两种用户进行身份验证和管理:直接登录到您的用户池的用户,以及通过外部身份提供商登录的用户。所有用户都具有由 Amazon Cognito 提供的配置文件和令牌。

本指南介绍了如何利用可自定义的用户体验以及与身份提供商的内置集成,来开始使用 Amazon Cognito 用户池。如果您希望构建自己的用户体验并使用我们的开发工具包将其连接到 Amazon Cognito 用户池,请参阅Amazon Cognito 用户池入门。如果您的应用程序需要获取联合身份用户的 AWS 凭证,但您不希望将联合身份用户链接到 Amazon Cognito 用户池配置文件或令牌,请参阅开始使用 Amazon Cognito 联合身份

将 Amazon Cognito 用户池设置为用户目录

用户池是一个用户目录,您可用它来注册和登录用户以及管理用户配置文件。用户池还在用户登录时为其提供令牌。您可以使用这些令牌来控制 (通过您的应用程序) 用户对资源 (如后端 API) 的访问。用户池可以包含直接登录的本机用户 (即,使用存储在用户池中的用户名和密码) 以及通过外部身份提供商登录的联合用户。您还可以将外部身份提供商用户属性 (例如,名称或电子邮件地址) 映射到用户池属性值中。本地和联合身份用户均具有用户配置文件,并在登录时接收用户池令牌,因此您可以将应用程序标准化来通过 Amazon Cognito 处理所有用户。

如果您还没有用户池,则可以从 Amazon Cognito 控制台创建和配置一个。有关更多信息,请参阅 快速入门:使用控制台创建新用户池逐步介绍 AWS 管理控制台中的 Amazon Cognito 用户池设置

要试用应用程序集成和联合功能,我们建议您在 Amazon Cognito 控制台中使用以下设置创建一个用户池:

  • Attributes 选项卡上,选择 Email address or phone number,然后选择 Allow email addresses

  • Policies 选项卡上,选择 Allow users to sign themselves up (默认值)。

  • Verifications 选项卡的 Do you want to require verification of emails or phone numbers? 下面,选择 Email (默认值)。

  • App clients 选项卡上,创建应用程序客户端。

配置应用程序集成

创建用户池后,Amazon Cognito 控制台将显示 App integration 选项卡,您在其中可以针对可自定义的内置 UI (用于注册和登录用户) 来配置设置。有关更多信息,请参阅 将移动和 Web 应用程序集成到 Amazon Cognito 用户池中

要使用应用程序集成,请在 Amazon Cognito 控制台中指定以下设置:

  1. App client settings 选项卡上:

    1. 选中对应的复选框以启用您希望允许用户在登录时使用的身份提供商。

      注意

      要允许您的用户使用外部身份提供商 (如 Facebook) 或 SAML 身份提供商进行登录,您首先要按下文所述的方式配置它们,然后返回到 App client settings 选项卡以启用它们。

    2. 输入一个回调 URL,供 Amazon Cognito 授权服务器在用户通过身份验证之后进行调用。对于 Web 应用程序,URL 必须以 https:// 开头。对于 iOS 或 Android 应用程序,您可以使用类似 myapp:// 的回调 URL。您可能希望在安装了开发工具包之后恢复到此设置。请参阅 将登录流与应用程序集成

    3. 对于 Allowed OAuth Flows,选择 Authorized code grantImplicit grant。只有在您的应用程序需要代表自己而不是代表用户请求访问令牌时才选择 Client credentials

    4. 除非您希望明确地排除一个允许的 OAuth 范围,否则请选中所有范围。

  2. Domain name 选项卡上,输入可用的域前缀。

  3. UI customization 选项卡上,您可以为托管最终用户页上传徽标,然后编辑 CSS 值以将更改外观,使之适合您的应用程序和品牌。

    注意

    通过利用您的用户池的特定信息构建以下 URL 并将它键入到浏览器中,您可以查看具有自定义项的托管 UI: https://<your_domain>/login?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url> 在控制台中进行的更改出现之前,您可能必须等待长达 1 分钟才能刷新浏览器。

    您的域显示在 Domain name 选项卡上。您的应用程序客户端 ID 和回调 URL 显示在 App client settings 选项卡上。

使用社交身份提供商配置联合身份验证

Amazon Cognito 用户池提供了与社交身份提供商 (如 Facebook、Google 和 Login with Amazon) 的内置集成。通过为 Amazon Cognito 用户池配置这些社交身份提供商,您可以快速轻松地添加它们以作为最终用户的登录选项。用户池成为了应用程序身份管理的单一点。您可以在 Amazon Cognito 控制台中添加一个或多个社交身份提供商,并且可以定义从社交份提供商到您的用户池中的用户属性的用户属性 (如电子邮件地址) 映射。

如果您不想让最终用户通过社交身份来登录,则可以跳过此步骤。

有关更多信息,请参阅添加社交身份提供商。要试用此功能,请在 Amazon Cognito 控制台中进行以下选择:

要添加社交身份提供商,您首先要通过该身份提供商创建一个开发人员账户。在拥有开发人员账户后,您应向身份提供商注册您的应用程序。身份提供商将为您的应用程序创建应用程序 ID 和应用程序密钥,然后您需要在您的用户池中配置这些值。

以下是帮助您开始使用社交身份提供商的一些链接:

您需要配置您的用户池域或使用身份提供商来重定向 URL。这可确保身份提供商在验证用户身份时接受 Amazon Cognito 提供的重定向 URL。

  • 对于 Google,请在 Google 应用程序的 Authorized redirect URIs (位于 Credentials 部分) 中添加您的 Amazon Cognito 用户池 URL (https://<your-user-pool-domain>/oauth2/idpresponse)。

  • 对于 Facebook,请在 Facebook 应用程序的 Settings (Basic) > Website URL 中添加您的 Amazon Cognito 用户池域 URL (https://<your-user-pool-domain>/)。

  • 对于 Login with Amazon,请将您的 Amazon Cognito 用户池域 URL (https://<your-user-pool-domain>/oauth2/idpresponse) 添加到 Login with Amazon 应用程序的 Allowed Return URLs

在 Amazon Cognito 用户池中配置社交身份提供商

  1. Identity providers 选项卡上,选择您的社交身份提供商对应的按钮:FacebookGoogleLogin with Amazon

  2. 输入您从身份提供商处收到的应用程序 ID 和应用程序密钥。

  3. 输入要授权的范围的名称。范围定义了您要通过应用程序访问的用户属性 (如 nameemail)。对于 Facebook,这些属性应采用逗号分隔 (例如,public_profile, email)。对于 Google 和 Login with Amazon,则应采用空格分隔。(Google 示例:profile email openid。Login with Amazon 示例:profile postal_code。)

    最终用户需要同意向您的应用程序提供这些属性。关于范围的更多信息,请参阅 Google、Facebook 和 Login with Amazon 的文档。

  4. 选择 Update Facebook (或者 GoogleAmazon)。

  5. Attribute mapping 选项卡上,至少为必需属性添加映射,通常是 email,如下所示:

    1. 选中此复选框以选择 Facebook、Google 或 Amazon 属性名称。您还可以输入未在 Amazon Cognito 控制台中列出的其他属性的名称。

    2. 从下拉列表中选择目标用户池属性。

使用 SAML 2.0 身份提供商配置联合身份验证

Amazon Cognito 用户池支持 SAML 2.0 与绑定后终端节点联合。这使您的应用程序不必检索或分析 SAML 断言响应,因为用户池直接通过用户代理从身份提供商接收 SAML 响应。Amazon Cognito 代表您的应用程序充当授权服务提供商。该用户池成为您应用程序的单一身份管理点,这样您的应用程序无需集成到多个 SAML 身份提供商。您可以在 Amazon Cognito 控制台中添加一个或多个 SAML 身份提供商,并且可以定义从 SAML 身份提供商 (通过 SAML 断言声明) 到您的用户池中的用户属性的用户属性 (如电子邮件地址) 映射。

如果您不想让最终用户通过 SAML 联合来登录,则可以跳过此步骤。要设置 SAML 身份提供商,您需要在 Amazon Cognito 和 SAML 身份提供商中执行一些配置任务。

您在 SAML 2.0 身份提供商中配置用户池作为依赖方或应用程序。有关更多信息,请参阅您身份提供商的文档。

您输入重定向或登录 URL,即 https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/saml2/idpresponse。您可以在 Amazon Cognito 控制台Domain name 选项卡上,查找您的用户池的域前缀和区域值。

注意

在 2017 年 8 月 10 日前的公开测试期间,您在用户池中创建的任何 SAML 身份提供商都具有重定向 URL https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/login/redirect。如果您的用户池中的公开测试版中具有这些 SAML 身份提供商之一,则必须执行以下操作之一:

  • 将其替换为使用新的重定向 URL 的新身份提供商。

  • 更新您的 SAML 身份提供商中的配置,以接受旧的和新的重定向 URL。

Amazon Cognito 中的所有 SAML 身份提供商都将切换到新的 URL,旧的 URL 将于 2017 年 10 月 31 日停止工作。

对于一些 SAML 身份提供商,您必须以 urn:amazon:cognito:sp:<yourUserPoolID> 格式提供 urn/受众 URI/SP 实体 ID。您可以在 Amazon Cognito 控制台的 App client settings 选项卡中查找用户池 ID。

您还必须配置 SAML 身份提供商,为您 用户池中需要的任意属性提供属性值。通常,email 是用户池的必需属性,在这种情况下,SAML 身份提供商必须在 SAML 断言中提供 email 值 (声明)。

在 Amazon Cognito 用户池中配置 SAML 2.0 身份提供商

有关更多信息,请参阅 从用户池使用联合身份验证。要试用此功能,请在 Amazon Cognito 控制台中进行以下选择:

  1. Identity providers 选项卡上,通过上传或输入来自 SAML 身份提供商的元数据文档的 URL,来创建新的提供商。有关元数据文档的更多信息,请参阅从用户池使用联合身份验证

  2. Attribute mapping 选项卡上,至少为必需属性添加映射,通常是 email,如下所示:

    1. 按照您的身份提供商提供的 SAML 断言中的显示,输入 SAML 属性名称。如果身份提供商提供了示例 SAML 断言,这可能有助于您查找名称。一些身份提供商使用简单名称,例如 email,另一些则使用类似于 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 的名称。

    2. 从下拉列表中选择目标用户池属性。

您可以使用 Amazon Cognito iOS、Android 和 JavaScript 开发工具包,将可自定义的登录流集成到移动或 Web 应用程序中。开发工具包可帮助您显示托管 UI、接收用户池令牌和刷新令牌。有关更多信息,请参阅随每个开发工具包提供的文档。

您的应用程序也可以直接构建请求并调用 Amazon Cognito 授权服务器。以下示例显示了托管登录页面并测试通过授权请求从浏览器登录:

https://<yourDomainPrefix>.auth.<region>.amazoncognito.com/oauth2/authorize? response_type=code& client_id=<yourAppClientId>& redirect_uri=<yourRedirectURL>& state=STATE& scope=email+phone+openid+profile+aws.cognito.signin.user.admin

有关更多信息,请参见 Amazon Cognito Auth API 参考

在何处查找适用于应用程序集成和联合的开发工具包和示例应用程序

您可在以下位置查找适用于 Amazon Cognito 用户池应用程序集成和联合的开发工具包和示例应用程序:

现在应该做什么

利用上述说明和开发工具包,您可以使用 Amazon Cognito 用户池将用户注册和登录 (具有社交身份或 SAML 联合) 添加到移动或 Web 应用程序。用户登录之后,您的应用程序可使用用户池配置文件管理用户,并使用用户池提供的令牌授予对您的 API 和资源的访问权限。如果您的应用程序需要使用这些用户池令牌来获取 AWS 凭证以访问资源 (例如在 S3 存储桶或 DynamoDB 表中),请参阅将用户池与联合身份集成。有关直接将 Amazon Cognito 用户池令牌用于 API 网关 的信息,请参阅 API 网关 开发人员指南 中的使用 Amazon Cognito 用户池