本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 用户池托管登录 您可以选择一个 Web 域来托管用户池的服务。当您添加域时，Amazon Cognito 用户池将获得以下功能，这些功能统称为*托管登录*。 + 一种[授权服务器](https://datatracker.ietf.org/doc/html/rfc6749#section-1.1)，充当使用 OAuth 2.0 和 OpenID Connect (OIDC) 的应用程序的身份提供者 (IdP)。授权服务器[路由请求、发出](authorization-endpoint.md)[和管理 JSON Web 令牌 (JWTs)](token-endpoint.md)，并[提供用户属性信息](userinfo-endpoint.md)。 + 用于登录、注销和密码管理等身份验证操作的 ready-to-use用户界面 (UI)。*托管登录页面*充当身份验证服务的 Web 前端。 + SAML 2.0、OIDC、Facebook、Lo IdPs gin with Amazon IdPs、使用苹果登录和谷歌的服务提供商 (SP) 或依赖方 (RP)。 与托管登录共享某些功能的另一个选项是经典的*托管 UI*。经典托管 UI 是托管登录服务的第一代版本。托管 UI IdP 和 RP 服务通常与托管登录具有相同的特征，但是登录页面的设计更简单，功能也更少。例如，通行密钥登录在经典托管 UI 中不可用。在精简版[功能计划](cognito-sign-in-feature-plans.md)中，经典托管 UI 是用户池域服务的唯一选择。 托管登录页面是一组 Web 界面，用于在用户池中进行基本注册、登录、多重身份验证和密码重置活动。当你想让用户选择登录选项时，它们还会将用户连接到一个或多个第三方身份提供商 (IdPs)。当您想要对用户进行身份验证和授权时，应用程序可以在用户的浏览器中调用托管登录页面。 您可以通过自定义徽标、背景和样式使托管登录用户体验适合您的品牌。您有两个品牌选项可能适用于托管登录 UI：适用于托管登录的*品牌编辑器*和适用于托管 UI 的*托管 UI（经典）品牌*。 **品牌编辑器** Amazon Cognito 控制台中提供了最多的 up-to-date身份验证选项和可视化编辑器，带来了更新的用户体验。 **托管 UI 品牌** Amazon Cognito 用户池的先前采用者所熟悉的用户体验。托管 UI 的品牌推广是一个基于文件的系统。要将品牌应用于托管 UI 页面，您需要上传一个徽标图像文件和一个为多个预定 CSS 样式选项设置值的文件。 品牌编辑器并非在用户池的所有功能计划中都可用。有关更多信息，请参阅 [用户池功能计划](cognito-sign-in-feature-plans.md)。 有关构造对托管登录和托管 UI 服务的请求的更多信息，请参阅[用户池端点和托管登录参考](cognito-userpools-server-contract-reference.md)。 **注意** Amazon Cognito 托管登录不支持使用[自定义身份验证质询 Lambda 触发器](user-pool-lambda-challenge.md)进行自定义身份验证。 **Topics** + [托管登录本地化](#managed-login-localization) + [条款文档](#managed-login-terms-documents) + [使用设置托管登录 Amazon Amplify](#cognito-user-pools-app-integration-amplify) + [使用 Amazon Cognito 控制台设置托管登录](#set-up-managed-login) + [查看您的登录页面](#view-login-pages) + [自定义身份验证页面](#cognito-user-pools-app-integration-customize-hosted-ui) + [托管登录和托管 UI 需知](#managed-login-things-to-know) + [配置用户池域](cognito-user-pools-assign-domain.md) + [将品牌应用于托管登录页面](managed-login-branding.md) ## 托管登录本地化 在用户交互式页面中，托管登录默认为英语。您可以显示您选择的语言的本地化托管登录页面。可用语言为在 Amazon Web Services 管理控制台中可用的语言。在分发给用户的链接中，请添加 `lang` 查询参数，如以下示例所示。 ``` https:///oauth2/authorize?lang=es&response_type=code&client_id=&redirect_uri= ``` Amazon Cognito 会在用户发出带有 `lang` 参数的初始请求后，在用户的浏览器中对他们的语言首选项设置一个 cookie。设置 cookie 后，语言选择将持续保留，无需在后续请求中显示或要求您在请求中包含该参数。例如，在用户使用 `lang=de` 参数发出登录请求后，他们的托管登录页面将以德语呈现，直到他们清除其 cookie 或使用新的本地化参数（例如 `lang=en`）提出新请求。 本地化仅适用于托管登录。您必须使用 Essentials 或 Plus [功能计划](cognito-sign-in-feature-plans.md)并且已分配域才能使用[托管登录品牌](managed-login-branding.md)。 用户在托管登录中所做的选择不可用于[自定义电子邮件或短信发件人触发器](user-pool-lambda-custom-sender-triggers.md)。在实施这些触发器时，必须使用其他机制来确定用户的首选语言。在登录流程中，`locale` 属性可能会根据位置指示用户的首选语言。在注册流程中，用户池的区域或应用程序客户端 ID 可能会指示语言首选项。 有以下语言可供选择。 **托管登录语言** | 语言 | 代码 | | --- | --- | | 德国料理 | de | | English | en | | 西班牙料理 | es | | 法式料理 | fr | | 印度尼西亚语 | id | | 意大利语 | 原 | | 日语 | ja | | 韩语 | ko | | 葡萄牙语（巴西） | pt-BR | | 中文（简体） | zh-CN | | 中文（繁体） | zh-TW | ## 条款文档 您可以将托管登录页面配置为在用户注册时显示指向**使用条款**和**隐私政策**文档的链接。在应用程序客户端中设置这两个条款文档时，用户在注册时会看到以下文本：**注册即表示您同意我们的使用条款和隐私政策**。**使用条款**和**隐私政策**这两个短语出现在您的托管登录页面中，并以超链接形式链接到您的文档。 术语文档支持与托管登录本地化 URLs 相一致的特定语言。当用户使用 `lang` 查询参数选择语言时，Amazon Cognito 将以该语言显示指向条款文档的链接。如果您尚未配置特定语言的 URL，Amazon Cognito 将使用您为应用程序客户端配置的默认 URL。 要为应用程序客户端配置条款文档，请导航到用户池中的**托管登录**菜单。在**条款文档**下，选择**创建条款文档**。 ------ #### [ Amazon Cognito console ] **创建条款文档** 1. 导航到用户池，然后选择**托管登录**菜单。找到**条款文档**。 1. 选择**创建条款文档**。 1. 选择要将条款文档分配到的应用程序客户端。 1. 输入**条款名称**。它在控制台中标识您的文档。 1. 在**链接**下，选择**语言**，然后输入以该语言托管条款文档的 **URL**。 1. 要 URLs 为其他语言添加，请选择**添加其他**语言。 1. 选择**创建**。 ------ #### [ Amazon Cognito user pools API ] 以下是一个示例 [CreateTerms](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_CreateTerms.html) 请求正文。它会导致应用程序客户端 `1example23456789` 的注册页面在托管登录本地化为法语和葡萄牙语（巴西）版本的隐私政策时呈现该语言的链接。在托管登录在注册页面呈现链接`terms-of-use`之前，需要设置 URLs 单独的请求。 ``` { "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 向网络或移动应用程序添加身份验证，则可以在 Amplify 命令行界面 (CLI) 中设置托管登录页面，在 Amplify 框架中设置库。要向应用程序添加身份验证功能，请将 `Auth` 类别添加到项目中。然后，在您的应用程序中，使用 Amplify 客户端库对用户池用户进行身份验证。 您可以调用托管登录页面进行身份验证，也可以通过重定向到 IdP 的授权端点联合用户。用户成功通过提供商身份验证之后，Amplify 在您的用户池中创建一个新用户，并将用户的令牌传递给您的应用程序。 以下示例说明 Amazon Amplify 如何使用在您的应用程序中设置社交服务提供商的托管登录。 + [React](https://docs.amplify.aws/react/build-a-backend/auth/concepts/external-identity-providers/) + [Swift](https://docs.amplify.aws/swift/build-a-backend/auth/concepts/external-identity-providers/) + [Flutter](https://docs.amplify.aws/flutter/build-a-backend/auth/concepts/external-identity-providers/) + [Android](https://docs.amplify.aws/android/build-a-backend/auth/concepts/external-identity-providers/) ## 使用 Amazon Cognito 控制台设置托管登录 托管登录和托管 UI 的第一个要求是用户池域。在用户池控制台中，导航到用户池的**域**选项卡，然后添加 **Cognito 域**或**自定义域**。您也可以在创建新用户池的过程中选择域。有关更多信息，请参阅 [配置用户池域](cognito-user-pools-assign-domain.md)。当某个域在您的用户池中处于活动状态时，所有应用程序客户端都会在该域上提供公共身份验证页面。 创建或修改用户池域时，将为您的域设置**品牌版本**。此品牌版本可以选择**托管登录**或**托管 UI（经典）**。您选择的品牌版本将应用于在您的域中使用登录服务的所有应用程序客户端。 下一步是从用户池的**应用程序客户端**选项卡创建[应用程序客户端](user-pool-settings-client-apps.md)。在创建应用程序客户端的过程中，Amazon Cognito 会要求您提供有关应用程序的信息，然后提示您选择**返回 URL**。返回 URL 也称为依赖方（RP）URL、重定向 URI 和回调 URL。这是据以运行您的应用程序的 URL，例如 `https://www.example.com` 或 `myapp://example`。 在用户池中配置具有品牌风格的域和应用程序客户端后，托管登录页面便可以在互联网上使用。 ## 查看您的登录页面 在 Amazon Cognito 控制台中，在**应用程序客户端**菜单下选择应用程序客户端**登录页面**选项卡中的**查看登录页面**按钮。此按钮会将您转到用户池域中的登录页面，其中包含以下基本参数。 + 应用程序客户端 id + 授权代码授予请求 + 对您为当前应用程序客户端激活的所有范围的请求 + 当前应用程序客户端列表中的第一个回调 URL 当您想要测试托管登录页面的基本功能时，**查看登录页面**按钮非常有用。您的登录页面将与您分配给[用户池域](cognito-user-pools-assign-domain.md)的**品牌版本**相匹配。您可以使用其他和修改后的参数自定义登录 URL。在大多数情况下，**查看登录页面**链接的自动生成的参数不完全符合您的应用程序需求。在这些情况下，您必须自定义应用程序在用户登录时调用的 URL。有关登录参数键和值的更多信息，请参阅 [用户池端点和托管登录参考](cognito-userpools-server-contract-reference.md)。 登录网页使用以下 URL 格式。此示例使用 `response_type=code` 参数请求授权码授予。 ``` https:///oauth2/authorize?response_type=code&client_id=&redirect_uri= ``` 您可以从用户池中的**域**菜单查找您的用户池域字符串。在**应用程序客户端**菜单中，您可以识别应用程序客户端 IDs、其回调 URLs、允许的范围和其他配置。 当您使用自定义参数导航到 `/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 推出了*托管登录*，这是一项更新的托管身份验证服务。*品牌编辑*器更新 look-and-feel了托管登录。品牌编辑器是一个无代码可视化编辑器，提供一套比托管 UI 自定义体验更多的选项。托管登录还引入了自定义背景图像和深色模式主题。 在用户池中，您可以在托管登录和托管 UI 品牌体验之间切换。要了解有关自定义托管登录页面的更多信息，请参阅[将品牌应用于托管登录页面](managed-login-branding.md)。 ## 托管登录和托管 UI 需知 **一小时托管登录和托管 UI 会话 Cookie** 当用户使用您的登录页面或第三方提供商登录时，Amazon Cognito 会在他们的浏览器中设置一个 Cookie。使用此 Cookie，用户可以在一小时内使用相同的身份验证方法再次登录。当他们使用浏览器 Cookie 登录时，他们会获得新的令牌，这些令牌将持续在应用程序客户端配置中指定的持续时间。用户属性或身份验证因素的更改不会影响他们使用其浏览器 Cookie 再次登录的能力。 使用会话 Cookie 进行身份验证不会将 Cookie 持续时间额外重置一小时。如果用户在最近一次成功进行交互式身份验证超过一个小时后尝试访问您的登录页面，则必须重新登录。 **确认用户账户并验证用户属性** 对于用户池[本地用户](cognito-terms.md#terms-localuser)，当您将用户池配置为**允许 Cognito 自动发送消息以进行验证和确认**时，托管登录和托管 UI 效果最佳。当您启用此设置时，Amazon Cognito 会向注册的用户发送一条包含确认码的消息。当您改而确认用户为用户池管理员时，在注册后登录页面会显示一条错误消息。在这种状态下，Amazon Cognito 已创建新用户，但无法发送验证消息。您仍然可以确认用户为管理员，但他们可能会在遇到错误后联系您的支持部门。有关管理确认的更多信息，请参阅[允许用户在您的应用程序中注册但以用户池管理员身份进行确认](signing-up-users-in-your-app.md#signing-up-users-in-your-app-and-confirming-them-as-admin)。 **托管登录操作范围** 托管登录和经典托管 UI 支持注册、登录和密码管理。这包括通过多重身份验证（MFA）和注册 webAuthn 身份验证器完成登录。托管登录不支持用户自助配置文件管理，例如属性更改和设置 MFA 首选项。您必须在自己的应用程序代码中实施配置文件管理。当您以管理员身份[AdminUpdateUserAttributes](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)通过 API 操作更新电子邮件地址和电话号码时，托管登录也无法确认属性更改。 **查看您对配置所做的更改** 如果您对页面做出样式更改但未立即显示这些更改，请等待几分钟，然后刷新页面。 **解码用户池令牌** Amazon Cognito 用户池令牌使用算法进行 RS256 签名。您可以使用解码和验证用户池令牌。 Amazon Lambda请参阅[解码和验证 Amazon Cognito J](https://github.com/awslabs/aws-support-tools/tree/master/Cognito/decode-verify-jwt) WT 令牌。 GitHub **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. [令牌端点](token-endpoint.md) 1. [撤销端点](revocation-endpoint.md) 1. [userInfo 端点](userinfo-endpoint.md) **Cookie** 托管登录和托管 UI 在用户的浏览器中设置 Cookie。这些 Cookie 符合某些浏览器的要求，即要求网站不能设置第三方 Cookie。它们的范围仅限于您的用户池端点，包括以下内容： + 每个请求有一个 `XSRF-TOKEN` Cookie。 + 一个 `csrf-state` Cookie，用于在重定向用户时保持会话一致性。 + 用于保持会话一致性的 `csrf-state-legacy` Cookie，当您的浏览器不支持 `SameSite` 属性时由 Amazon Cognito 以回退的形式进行读取。 + 一个 `cognito` 会话 Cookie，用于将成功的登录尝试保留一小时。 + 一个用于在托管登录中保持用户对[语言本地化](#managed-login-localization)的选择的 `lang` Cookie。 + 一个当用户在托管登录页面之间导航时保留所需数据的 `page-data` Cookie。 在 iOS 中，您可以[阻止所有 Cookie](https://support.apple.com/en-us/105082)。此设置与托管登录或托管 UI 不兼容。要与可能启用此设置的用户合作，请使用 Amazon SDK 将用户池身份验证构建到原生 iOS 应用程序中。在这种情况下，您可以构建自己的会话存储，该存储不依赖 Cookie。 **托管登录版本更改的影响** 请考虑添加域和设置托管登录版本的以下影响。 + 当您添加带有托管登录或托管 UI（经典）品牌的前缀域时，登录页面可能需要长达 60 秒钟才可用。 + 当您添加带有托管登录或托管 UI（经典）品牌的自定义域时，登录页面可能需要长达五分钟才可用。 + 当您更改域的品牌版本时，可能需要长达四分钟，登录页面才会在新的品牌版本中可用。 + 当您在托管登录和托管 UI（经典）品牌之间切换时，Amazon Cognito 不会维护用户会话。他们必须使用新界面重新登录。 **默认风格** 当您在中创建应用程序客户端时 Amazon Web Services 管理控制台，Amazon Cognito 会自动为您的应用程序客户端分配品牌风格。当您通过该[CreateUserPoolClient](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html)操作以编程方式创建应用程序客户端时，不会创建任何品牌风格。在您使用[CreateManagedLoginBranding](https://docs.amazonaws.cn/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)请求创建应用程序客户端之前，托管登录不可用于使用 Amazon SDK 创建的应用程序客户端。 **托管登录身份验证提示超时** Amazon Cognito 会取消未在五分钟内完成的身份验证请求，并将用户重定向到托管登录。页面随即显示 `Something went wrong` 错误消息。