用户池托管登录 - Amazon Cognito
托管登录本地化条款文档使用 Amazon Amplify 设置托管登录使用 Amazon Cognito 控制台设置托管登录查看您的登录页面自定义身份验证页面托管登录和托管 UI 需知
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

用户池托管登录

您可以选择一个 Web 域来托管用户池的服务。当您添加域时，Amazon Cognito 用户池将获得以下功能，这些功能统称为托管登录。

  • 一个授权服务器，充当使用 OAuth 2.0 和 OpenID Connect（OIDC）的应用程序的身份提供者（IdP）。授权服务器路由请求，发布和管理 JSON Web 令牌（JWT），并提供用户属性信息。

  • 即用型用户界面（UI），用于登录、注销和密码管理等身份验证操作。托管登录页面充当身份验证服务的 Web 前端。

  • SAML 2.0 IdP、OIDC IdP、Facebook、Login with Amazon、Sign in with Apple 和 Google 对应的服务提供商（SP）或依赖方（RP）。

与托管登录共享某些功能的另一个选项是经典的托管 UI。经典托管 UI 是托管登录服务的第一代版本。托管 UI IdP 和 RP 服务通常与托管登录具有相同的特征，但是登录页面的设计更简单，功能也更少。例如，通行密钥登录在经典托管 UI 中不可用。在精简版功能计划中，经典托管 UI 是用户池域服务的唯一选择。

托管登录页面是一组 Web 界面，用于在用户池中进行基本注册、登录、多重身份验证和密码重置活动。当您想让用户选择登录选项时，这些页面还会将用户连接到一个或多个第三方身份提供者（IdP）。当您想要对用户进行身份验证和授权时，应用程序可以在用户的浏览器中调用托管登录页面。

您可以通过自定义徽标、背景和样式使托管登录用户体验适合您的品牌。您有两个品牌选项可能适用于托管登录 UI：适用于托管登录的品牌编辑器和适用于托管 UI 的托管 UI（经典）品牌。

品牌编辑器

Amazon Cognito 控制台中一种更新的用户体验，具有最新的身份验证选项和可视化编辑器。

托管 UI 品牌

Amazon Cognito 用户池的先前采用者所熟悉的用户体验。托管 UI 的品牌推广是一个基于文件的系统。要将品牌应用于托管 UI 页面，您需要上传一个徽标图像文件和一个为多个预定 CSS 样式选项设置值的文件。

品牌编辑器并非在用户池的所有功能计划中都可用。有关更多信息，请参阅用户池功能计划。

有关构造对托管登录和托管 UI 服务的请求的更多信息，请参阅用户池端点和托管登录参考。

注意

Amazon Cognito 托管登录不支持使用自定义身份验证质询 Lambda 触发器进行自定义身份验证。

主题

托管登录本地化

在用户交互式页面中，托管登录默认为英语。您可以显示您选择的语言的本地化托管登录页面。可用语言为在 Amazon Web Services 管理控制台中可用的语言。在分发给用户的链接中，请添加 lang 查询参数，如以下示例所示。

https://<your domain>/oauth2/authorize?lang=es&response_type=code&client_id=<your app client id>&redirect_uri=<your relying-party url>

Amazon Cognito 会在用户发出带有 lang 参数的初始请求后，在用户的浏览器中对他们的语言首选项设置一个 cookie。设置 cookie 后，语言选择将持续保留，无需在后续请求中显示或要求您在请求中包含该参数。例如，在用户使用 lang=de 参数发出登录请求后，他们的托管登录页面将以德语呈现，直到他们清除其 cookie 或使用新的本地化参数（例如 lang=en）提出新请求。

本地化仅适用于托管登录。您必须使用 Essentials 或 Plus 功能计划并且已分配域才能使用托管登录品牌。

用户在托管登录中所做的选择不可用于自定义电子邮件或短信发件人触发器。在实施这些触发器时，必须使用其他机制来确定用户的首选语言。在登录流程中，locale 属性可能会根据位置指示用户的首选语言。在注册流程中，用户池的区域或应用程序客户端 ID 可能会指示语言首选项。

有以下语言可供选择。

托管登录语言
语言 代码
德语 de
English en
西班牙语 es
法语 fr
印度尼西亚语 id
意大利语 它
日语 ja
韩语 ko
葡萄牙语（巴西） pt-BR
中文（简体） zh-CN
中文（繁体） zh-TW

条款文档

您可以将托管登录页面配置为在用户注册时显示指向使用条款和隐私政策文档的链接。在应用程序客户端中设置这两个条款文档时，用户在注册时会看到以下文本：注册即表示您同意我们的使用条款和隐私政策。使用条款和隐私政策这两个短语出现在您的托管登录页面中，并以超链接形式链接到您的文档。

条款文档支持语言特定的 URL，它们与托管登录本地化一致。当用户使用 lang 查询参数选择语言时，Amazon Cognito 将以该语言显示指向条款文档的链接。如果您尚未配置特定语言的 URL，Amazon Cognito 将使用您为应用程序客户端配置的默认 URL。

要为应用程序客户端配置条款文档，请导航到用户池中的托管登录菜单。在条款文档下，选择创建条款文档。

Amazon Cognito console
创建条款文档

  1. 导航到用户池，然后选择托管登录菜单。找到条款文档。

  2. 选择创建条款文档。

  3. 选择要将条款文档分配到的应用程序客户端。

  4. 输入条款名称。它在控制台中标识您的文档。

  5. 在链接下，选择语言，然后输入以该语言托管条款文档的 URL。

  6. 要为其他语言添加 URL，请选择添加另一个。

  7. 选择创建。

Amazon Cognito user pools API

以下是一个示例 CreateTerms 请求正文。它会导致应用程序客户端 1example23456789 的注册页面在托管登录本地化为法语和葡萄牙语（巴西）版本的隐私政策时呈现该语言的链接。在托管登录在注册页面上呈现链接之前，需要另外请求设置 terms-of-use 的 URL。

{
   "ClientId": "1example23456789",
   "Enforcement": "NONE",
   "Links": { 
      "cognito:default" : "https://example.com/privacy/",
      "cognito:french" : "https://example.com/fr/privacy/",
      "cognito:portuguese-brazil" : "https://example.com/pt/privacy/"
   },
   "TermsName": "privacy-policy",
   "TermsSource": "LINK",
   "UserPoolId": "us-east-1_EXAMPLE"
}
注意

在 Amazon Cognito 在托管登录页面中显示条款文档之前，您必须为应用程序客户端创建使用条款和隐私政策文档。

使用 Amazon Amplify 设置托管登录

如果您使用 Amazon Amplify 向 Web 或移动应用程序添加身份验证功能，则可以在 Amplify Framework 中的 Amplify 命令行界面（CLI）和库中设置托管登录页面。要向应用程序添加身份验证功能，请将 Auth 类别添加到项目中。然后，在您的应用程序中，使用 Amplify 客户端库对用户池用户进行身份验证。

您可以调用托管登录页面进行身份验证，也可以通过重定向到 IdP 的授权端点联合用户。用户成功通过提供商身份验证之后，Amplify 在您的用户池中创建一个新用户，并将用户的令牌传递给您的应用程序。

以下示例显示如何在应用程序中使用 Amazon Amplify 设置社交服务提供商的托管登录。

使用 Amazon Cognito 控制台设置托管登录

托管登录和托管 UI 的第一个要求是用户池域。在用户池控制台中，导航到用户池的域选项卡，然后添加 Cognito 域或自定义域。您也可以在创建新用户池的过程中选择域。有关更多信息，请参阅配置用户池域。当某个域在您的用户池中处于活动状态时，所有应用程序客户端都会在该域上提供公共身份验证页面。

创建或修改用户池域时，将为您的域设置品牌版本。此品牌版本可以选择托管登录或托管 UI（经典）。您选择的品牌版本将应用于在您的域中使用登录服务的所有应用程序客户端。

下一步是从用户池的应用程序客户端选项卡创建应用程序客户端。在创建应用程序客户端的过程中，Amazon Cognito 会要求您提供有关应用程序的信息，然后提示您选择返回 URL。返回 URL 也称为依赖方（RP）URL、重定向 URI 和回调 URL。这是据以运行您的应用程序的 URL，例如 https://www.example.com 或 myapp://example。

在用户池中配置具有品牌风格的域和应用程序客户端后，托管登录页面便可以在互联网上使用。

查看您的登录页面

在 Amazon Cognito 控制台中，在应用程序客户端菜单下选择应用程序客户端登录页面选项卡中的查看登录页面按钮。此按钮会将您转到用户池域中的登录页面，其中包含以下基本参数。

  • 应用程序客户端 id

  • 授权代码授予请求

  • 对您为当前应用程序客户端激活的所有范围的请求

  • 当前应用程序客户端列表中的第一个回调 URL

当您想要测试托管登录页面的基本功能时，查看登录页面按钮非常有用。您的登录页面将与您分配给用户池域的品牌版本相匹配。您可以使用其他和修改后的参数自定义登录 URL。在大多数情况下，查看登录页面链接的自动生成的参数不完全符合您的应用程序需求。在这些情况下，您必须自定义应用程序在用户登录时调用的 URL。有关登录参数键和值的更多信息，请参阅 用户池端点和托管登录参考。

登录网页使用以下 URL 格式。此示例使用 response_type=code 参数请求授权码授予。

https://<your domain>/oauth2/authorize?response_type=code&client_id=<your app client id>&redirect_uri=<your relying-party url>

您可以从用户池中的域菜单查找您的用户池域字符串。在应用程序客户端菜单中，您可以标识应用程序客户端 ID 及其回调 URL、允许的范围和其他配置。

当您使用自定义参数导航到 /oauth2/authorize 端点时，Amazon Cognito 会将您重定向到 /oauth2/login 端点，或者在您具有 identity_provider 或 idp_identifier 参数时，静默地将您重定向到 IdP 登录页面。

隐式授予的示例请求

您可以使用针对隐式代码授予的以下 URL 查看登录网页，其中 response_type=token。成功登录后，Amazon Cognito 会将用户池令牌返回到您的 Web 浏览器的地址栏。


            https://mydomain.auth.us-east-1.amazoncognito.com/authorize?response_type=token&client_id=1example23456789&redirect_uri=https://mydomain.example.com

身份令牌和访问令牌显示为附加到您的重定向 URL 的参数。

以下内容是来自隐式授予请求的示例响应。


            https://auth.example.com/#id_token=eyJraaBcDeF1234567890&access_token=eyJraGhIjKlM1112131415&expires_in=3600&token_type=Bearer

自定义身份验证页面

过去，Amazon Cognito 仅使用经典托管 UI 托管登录页面，这是一种向身份验证网页授予通用外观的简单设计。您可以使用徽标图像自定义 Amazon Cognito 用户池，也可以使用指定某些 CSS 样式值的文件调整某些样式。后来，Amazon Cognito 推出了托管登录，这是一项更新的托管身份验证服务。托管登录是一种更新的外观，具有品牌编辑器。品牌编辑器是一个无代码可视化编辑器，提供一套比托管 UI 自定义体验更多的选项。托管登录还引入了自定义背景图像和深色模式主题。

在用户池中，您可以在托管登录和托管 UI 品牌体验之间切换。要了解有关自定义托管登录页面的更多信息，请参阅将品牌应用于托管登录页面。

托管登录和托管 UI 需知

一小时托管登录和托管 UI 会话 Cookie

当用户使用您的登录页面或第三方提供商登录时，Amazon Cognito 会在他们的浏览器中设置一个 Cookie。使用此 Cookie，用户可以在一小时内使用相同的身份验证方法再次登录。当他们使用浏览器 Cookie 登录时，他们会获得新的令牌，这些令牌将持续在应用程序客户端配置中指定的持续时间。用户属性或身份验证因素的更改不会影响他们使用其浏览器 Cookie 再次登录的能力。

使用会话 Cookie 进行身份验证不会将 Cookie 持续时间额外重置一小时。如果用户在最近一次成功进行交互式身份验证超过一个小时后尝试访问您的登录页面，则必须重新登录。

确认用户账户并验证用户属性

对于用户池本地用户，当您将用户池配置为允许 Cognito 自动发送消息以进行验证和确认时，托管登录和托管 UI 效果最佳。当您启用此设置时，Amazon Cognito 会向注册的用户发送一条包含确认码的消息。当您改而确认用户为用户池管理员时，在注册后登录页面会显示一条错误消息。在这种状态下，Amazon Cognito 已创建新用户，但无法发送验证消息。您仍然可以确认用户为管理员，但他们可能会在遇到错误后联系您的支持部门。有关管理确认的更多信息，请参阅允许用户在您的应用程序中注册但以用户池管理员身份进行确认。

托管登录操作范围

托管登录和经典托管 UI 支持注册、登录和密码管理。这包括通过多重身份验证（MFA）和注册 webAuthn 身份验证器完成登录。托管登录不支持用户自助配置文件管理，例如属性更改和设置 MFA 首选项。您必须在自己的应用程序代码中实施配置文件管理。当您以管理员身份使用 AdminUpdateUserAttributes API 操作更新电子邮件地址和电话号码时，托管登录也无法确认属性更改。

查看您对配置所做的更改

如果您对页面做出样式更改但未立即显示这些更改，请等待几分钟，然后刷新页面。

解码用户池令牌

使用 RS256 算法对 Amazon Cognito 用户池令牌进行签名。您可以使用 Amazon Lambda 解码和验证用户池令牌。请参阅 GitHub 上的解码并验证 Amazon Cognito JWT 令牌。

TLS 版本

托管登录和托管 UI 页面要求在传输过程中进行加密。Amazon Cognito 提供的用户池域要求用户浏览器支持的最低 TLS 版本为 1.2。自定义域支持 TLS 版本 1.2 的浏览器连接。托管 UI（经典）对自定义域不要求使用 TLS 1.2，但较新的托管登录对自定义域和前缀域要求使用 TLS 版本 1.2。由于 Amazon Cognito 管理域服务的配置，因此您无法修改用户池域的 TLS 要求。

CORS 策略

托管登录或托管 UI 都不支持自定义跨源资源共享（CORS）源策略。CORS 策略将阻止用户在其请求中传递身份验证参数，应在应用程序前端实施 CORS 策略。Amazon Cognito 对发往以下端点的请求返回 Access-Control-Allow-Origin: * 响应标头。

  1. 令牌端点

  2. 撤销端点

  3. userInfo 端点

Cookie

托管登录和托管 UI 在用户的浏览器中设置 Cookie。这些 Cookie 符合某些浏览器的要求，即要求网站不能设置第三方 Cookie。它们的范围仅限于您的用户池端点，包括以下内容：

  • 每个请求有一个 XSRF-TOKEN Cookie。

  • 一个 csrf-state Cookie，用于在重定向用户时保持会话一致性。

  • 用于保持会话一致性的 csrf-state-legacy Cookie，当您的浏览器不支持 SameSite 属性时由 Amazon Cognito 以回退的形式进行读取。

  • 一个 cognito 会话 Cookie，用于将成功的登录尝试保留一小时。

  • 一个用于在托管登录中保持用户对语言本地化的选择的 lang Cookie。

  • 一个当用户在托管登录页面之间导航时保留所需数据的 page-data Cookie。

在 iOS 中，您可以阻止所有 Cookie。此设置与托管登录或托管 UI 不兼容。要与可能会启用此设置的用户合作，请使用 Amazon SDK 将用户池身份验证构建到原生 iOS 应用程序中。在这种情况下，您可以构建自己的会话存储，该存储不依赖 Cookie。

托管登录版本更改的影响

请考虑添加域和设置托管登录版本的以下影响。

  • 当您添加带有托管登录或托管 UI（经典）品牌的前缀域时，登录页面可能需要长达 60 秒钟才可用。

  • 当您添加带有托管登录或托管 UI（经典）品牌的自定义域时，登录页面可能需要长达五分钟才可用。

  • 当您更改域的品牌版本时，可能需要长达四分钟，登录页面才会在新的品牌版本中可用。

  • 当您在托管登录和托管 UI（经典）品牌之间切换时，Amazon Cognito 不会维护用户会话。他们必须使用新界面重新登录。

默认风格

当您在 Amazon Web Services 管理控制台中创建应用程序客户端时，Amazon Cognito 会自动为您的应用程序客户端分配品牌风格。当您使用 CreateUserPoolClient 操作以编程方式创建应用程序客户端时，不会创建任何品牌风格。在您使用 CreateManagedLoginBranding 请求创建之前，托管登录不可用于使用 Amazon SDK 创建的应用程序客户端。

托管登录身份验证提示超时

Amazon Cognito 会取消未在五分钟内完成的身份验证请求，并将用户重定向到托管登录。页面随即显示 Something went wrong 错误消息。