本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 用户池托管登录 您可以选择一个 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) + [使用设置托管登录 AWS 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) ## 托管登录本地化 在用户交互式页面中，托管登录默认为英语。您可以显示您选择的语言的本地化托管登录页面。可用语言为在 AWS 管理控制台中可用的语言。在分发给用户的链接中，请添加 `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.aws.amazon.com/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 在托管登录页面中显示条款文档之前，您必须为应用程序客户端创建使用条款和隐私政策文档。 ## 使用设置托管登录 AWS Amplify 如果您使用 AWS Amplify 向网络或移动应用程序添加身份验证，则可以在 Amplify 命令行界面 (CLI) 中设置托管登录页面，在 Amplify 框架中设置库。要向应用程序添加身份验证功能，请将 `Auth` 类别添加到项目中。然后，在您的应用程序中，使用 Amplify 客户端库对用户池用户进行身份验证。 您可以调用托管登录页面进行身份验证，也可以通过重定向到 IdP 的授权端点联合用户。用户成功通过提供商身份验证之后，Amplify 在您的用户池中创建一个新用户，并将用户的令牌传递给您的应用程序。 以下示例说明 AWS 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.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)通过 API 操作更新电子邮件地址和电话号码时，托管登录也无法确认属性更改。 **查看您对配置所做的更改** 如果您对页面做出样式更改但未立即显示这些更改，请等待几分钟，然后刷新页面。 **解码用户池令牌** Amazon Cognito 用户池令牌使用算法进行 RS256 签名。您可以使用解码和验证用户池令牌。 AWS 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 不兼容。要与可能启用此设置的用户合作，请使用 AWS SDK 将用户池身份验证构建到原生 iOS 应用程序中。在这种情况下，您可以构建自己的会话存储，该存储不依赖 Cookie。 **托管登录版本更改的影响** 请考虑添加域和设置托管登录版本的以下影响。 + 当您添加带有托管登录或托管 UI（经典）品牌的前缀域时，登录页面可能需要长达 60 秒钟才可用。 + 当您添加带有托管登录或托管 UI（经典）品牌的自定义域时，登录页面可能需要长达五分钟才可用。 + 当您更改域的品牌版本时，可能需要长达四分钟，登录页面才会在新的品牌版本中可用。 + 当您在托管登录和托管 UI（经典）品牌之间切换时，Amazon Cognito 不会维护用户会话。他们必须使用新界面重新登录。 **默认风格** 当您在中创建应用程序客户端时 AWS 管理控制台，Amazon Cognito 会自动为您的应用程序客户端分配品牌风格。当您通过该[CreateUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolClient.html)操作以编程方式创建应用程序客户端时，不会创建任何品牌风格。在您使用[CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)请求创建应用程序客户端之前，托管登录不可用于使用 AWS SDK 创建的应用程序客户端。 **托管登录身份验证提示超时** Amazon Cognito 会取消未在五分钟内完成的身份验证请求，并将用户重定向到托管登录。页面随即显示 `Something went wrong` 错误消息。 # 配置用户池域 配置域是设置用户池的可选部分。用户池域托管用于用户身份验证、与第三方提供者的联合身份验证以及 OpenID Connect（OIDC）流等功能。它具有*托管登录*，这是用于执行注册、登录和密码恢复等密钥操作的预构建界面。它还托管标准 OpenID Connect (OIDC) 端点，例如授权[、](authorization-endpoint.md)[用户信息和](userinfo-endpoint.md)[令牌](token-endpoint.md)，用于 machine-to-machine (M2M) 授权以及其他 OIDC 和 2.0 身份验证和授权流程。 OAuth 用户在与您的用户池关联的域中使用托管登录页面进行身份验证。您可以通过两种方式配置此域：您可以使用默认 Amazon Cognito 托管域，也可以配置自己拥有的自定义域。 自定义域选项在灵活性、安全性和控制性方面有更多选择。例如，一个熟悉的、由组织拥有的域可以增强用户信任并使登录过程更加直观。但是，自定义域名方法需要一些额外的开销，例如管理 SSL 证书和 DNS 配置的开销。 终端节点 URLs 和`/.well-known/jwks.json`令牌签名密钥`/.well-known/openid-configuration`的 OIDC 发现端点未托管在您的域中。有关更多信息，请参阅 [身份提供者和依赖方端点](federation-endpoints.md)。 了解如何为您的用户池配置和管理域，这是将身份验证集成到应用程序中的重要一步。使用用户池 API 和 S AWS DK 登录可以替代配置网域。基于 API 的模型直接在 API 响应中提供令牌，但是对于使用用户池扩展功能作为 OIDC IdP 的实现，必须配置域。有关用户池中可用的身份验证模型的更多信息，请参阅[了解 API、OIDC 和托管登录页面身份验证](authentication-flows-public-server-side.md#user-pools-API-operations)。 **Topics** + [用户池域需知信息](#cognito-user-pools-assign-domain-things-to-know) + [使用 Amazon Cognito 前缀域进行托管登录](cognito-user-pools-assign-domain-prefix.md) + [使用您自己的域进行托管登录](cognito-user-pools-add-custom-domain.md) ## 用户池域需知信息 用户池域是应用程序中的 OIDC 依赖方和 UI 元素的服务点。当您计划为用户池实施域时，请考虑以下详细信息。 **保留术语** 您不能在 Amazon Cognito 前缀域的名称中使用文本 `aws`、`amazon` 或 `cognito`。 **发现端点位于另一个域中** 用户池[发现端点](federation-endpoints.md) `.well-known/openid-configuration` 和 `.well-known/jwks.json` 不在您的用户池自定义域或前缀域中。这些端点的路径如下所示。 + `https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/openid-configuration` + `https://cognito-idp.Region.amazonaws.com/your user pool ID/.well-known/jwks.json` **域变更的生效时间** Amazon Cognito 可能需要长达一分钟的时间才能启动或更新前缀域的品牌版本。对自定义域的更改最长可能需要五分钟才能传播。新自定义域最长可能需要一小时才能传播。 **同时使用自定义域和前缀域** 您可以使用自定义域名和拥有的前缀域名来设置用户池 AWS。由于用户池[发现端点](federation-endpoints.md)托管在另一个域中，因此它们仅为*自定义域*提供服务。例如，您的 `openid-configuration` 将为 `"authorization_endpoint"` 提供单个值：`"https://auth.example.com/oauth2/authorize"`。 当用户池中同时包含自定义域和前缀域时，您可以使用自定义域来启用 OIDC 提供程序的完整特征。具有此配置的用户池中的前缀域没有发现或 token-signing-key端点，因此应相应地使用。 **首选自定义域作为通行密钥的依赖方 ID** 使用[通行密钥](amazon-cognito-user-pools-authentication-flow-methods.md#amazon-cognito-user-pools-authentication-flow-methods-passkey)设置用户池身份验证时，必须设置依赖方（RP）ID。如果同时具有自定义域和前缀域，则只能将 RP ID 设置为自定义域。要在 Amazon Cognito 控制台中将前缀域设置为 RP ID，请删除您的自定义域，或将前缀域的完全限定的域名（FQDN）作为**第三方域**进行输入。 **不要在域层次结构的不同级别使用自定义域** 您可以为不同的用户池配置独立的自定义域，并且这些域可以共享同一个顶级域（TLD），例如 *auth.example.com* 和 *auth2.example.com*。托管登录会话 Cookie 对自定义域和所有子域（如 *\$1.auth.example.com*）均有效。因此，您的应用程序的任何用户都不应访问任何父域*和*子域的托管登录。如果自定义域使用相同的 TLD，则应将其保持在相同的子域级别。 假设您有一个使用自定义域 *auth.example.com* 的用户池。然后创建另一个用户池并分配自定义域 *uk.auth.example.com*。用户使用 *auth.example.com* 登录，并获得 Cookie，他们的浏览器会将其呈现给通配符路径 *\$1.auth.example.com* 中的任何网站。然后他们尝试登录 *uk.auth.example.com*。他们向用户池域传递无效 Cookie，将收到错误信息，而不是收到登录提示。相比之下，拥有 *\$1.auth.example.com* 的 Cookie 的用户可以在 *auth2.example.com* 启动登录会话，而不会遇到任何问题。 **品牌版本** 创建域时可设置**品牌版本**。您可以选择更新的托管登录体验或经典的托管 UI 体验。这一选择适用于在您的域中托管服务的所有应用程序客户端。 # 使用 Amazon Cognito 前缀域进行托管登录 托管登录的默认体验托管在 AWS 拥有的网域上。这种方法的进入门槛较低（选择一个前缀名称即可生效），但该方法没有自定义域所具有的值得信任的特征。Amazon Cognito 域选项和自定义域选项在费用上没有差异。唯一的差异是您引导用户访问的 Web 地址中的域。对于第三方 IdP 重定向和客户端凭证流，托管域几乎没有明显的影响。自定义域更适合以下情况，即，您的用户使用托管登录进行登录，并且会与不匹配应用程序域的身份验证域进行交互。 托管的 Amazon Cognito 域有您选择的前缀，但托管在根域 `amazoncognito.com`。以下是示例： ``` https://cognitoexample.auth.ap-south-1.amazoncognito.com ``` 所有前缀域都遵循以下格式：`prefix`.`auth`.*`AWS 区域 code`*.`amazoncognito`.`com`。[自定义域](cognito-user-pools-add-custom-domain.md)用户池可以在您拥有的任何域中对托管登录或托管 UI 页面进行托管。 **注意** 为了增强您的 Amazon Cognito 应用程序的安全性，用户池端点的父域将在[公共后缀列表 (PSL)](https://publicsuffix.org/) 中注册。PSL 可帮助用户的网络浏览器对您的用户池端点及其设置的 Cookie 建立一致的理解。 用户池父域采用以下格式。 ``` auth.Region.amazoncognito.com auth-fips.Region.amazoncognito.com ``` 要使用添加应用程序客户端和用户池域 AWS 管理控制台，请参阅[创建应用程序客户端](user-pool-settings-client-apps.md#cognito-user-pools-app-idp-settings-console-create)。 **Topics** + [先决条件](#cognito-user-pools-assign-domain-prefix-prereq) + [配置 Amazon Cognito 域前缀](#cognito-user-pools-assign-domain-prefix-step-1) + [验证登录页面](#cognito-user-pools-assign-domain-prefix-verify) ## 先决条件 在开始之前，您需要： + 用户池和应用程序客户端。有关更多信息，请参阅 [用户池入门](getting-started-user-pools.md)。 ## 配置 Amazon Cognito 域前缀 您可以使用 AWS 管理控制台 或 AWS CLI 或 API 来配置用户池域。 ------ #### [ Amazon Cognito console ] **配置域** 1. 导航到**品牌**下的**域**菜单。 1. 选择**域**旁边的**操作**，然后选择**创建 Cognito 域**。如果您已配置用户池前缀域，请先选择**删除 Cognito 域**，然后再创建新的自定义域。 1. 输入可用的域前缀，以与 **Amazon Cognito 域**结合使用。有关设置**自定义域**的信息，请参阅[使用您自己的域进行托管登录](cognito-user-pools-add-custom-domain.md)。 1. 选择**品牌版本**。您的品牌版本适用于该域的所有用户交互页面。您的用户池可以针对所有应用程序客户端，对托管登录或托管 UI 品牌进行托管。 **注意** 您可以拥有自定义域和前缀域，但是 Amazon Cognito 仅为*自定义*域处理 `/.well-known/openid-configuration` 端点。 1. 选择**创建**。 ------ #### [ CLI/API ] 使用以下命令可以创建域前缀并将其分配到您的用户池。 **配置用户池域** + AWS CLI: `aws cognito-idp create-user-pool-domain` **示例**：`aws cognito-idp create-user-pool-domain --user-pool-id --domain --managed-login-version 2` + 用户池 API 操作：[CreateUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolDomain.html) **获取有关域的信息** + AWS CLI: `aws cognito-idp describe-user-pool-domain` **示例**：`aws cognito-idp describe-user-pool-domain --domain ` + 用户池 API 操作：[DescribeUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolDomain.html) **删除域** + AWS CLI: `aws cognito-idp delete-user-pool-domain` **示例**：`aws cognito-idp delete-user-pool-domain --domain ` + 用户池 API 操作：[DeleteUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteUserPoolDomain.html) ------ ## 验证登录页面 + 验证登录页面是否可从您的 Amazon Cognito 托管域访问。 ``` https:///login?response_type=code&client_id=&redirect_uri= ``` 您的域显示在 Amazon Cognito 控制台的 **Domain name (域名)** 页面上。您的应用程序客户端 ID 和回调 URL 将显示在 **App client settings**（应用程序客户端设置）页面上。 # 使用您自己的域进行托管登录 在设置应用程序客户端后，您可以为[托管登录](cognito-user-pools-managed-login.md)的域服务使用自定义域来配置用户池。使用自定义域，用户就可以使用您自己的网址而不是默认的 `amazoncognito.com` [前缀域](cognito-user-pools-assign-domain-prefix.md)来登录您的应用程序。自定义域让您可以使用熟悉的域名，从而提高用户对您的应用程序的信任度，尤其是当根域与托管应用程序的域匹配时。使用自定义域，可以进一步满足组织的安全要求。 自定义域有一些先决条件，包括用户池、应用程序客户端和您拥有的 Web 域。自定义域名还需要使用位于美国东部（弗吉尼亚北部）的 AWS Certificate Manager (ACM) 管理的自定义域名的 SSL 证书。Amazon Cognito 会创建亚马逊 CloudFront 配送，在运输途中使用您的 ACM 证书进行保护。由于您拥有该域名，因此必须创建 DNS 记录，将流量引导至自定义域名的 CloudFront 分配。 在这些要素准备就绪后，您可以通过 Amazon Cognito 控制台或 API 将自定义域添加到用户池。这包括指定域名和 SSL 证书，然后使用提供的别名目标更新 DNS 配置。在进行这些更改后，您可以验证是否可从您的自定义域访问登录页面。 创建自定义域最省力的方法是在 Amazon Route 53 中使用公有托管区。Amazon Cognito 控制台只需几个步骤即可创建正确的 DNS 记录。在开始之前，请考虑为您拥有的域或子域[创建 Route 53 托管区](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html)。 **Topics** + [将自定义域添加到用户池](#cognito-user-pools-add-custom-domain-adding) + [先决条件](#cognito-user-pools-add-custom-domain-prereq) + [步骤 1：输入自定义域名](#cognito-user-pools-add-custom-domain-console-step-1) + [步骤 2：添加别名目标和子域](#cognito-user-pools-add-custom-domain-console-step-2) + [步骤 3：验证登录页面](#cognito-user-pools-add-custom-domain-console-step-3) + [更改自定义域的 SSL 证书](#cognito-user-pools-add-custom-domain-changing-certificate) ## 将自定义域添加到用户池 要将自定义域添加到用户池，请在 Amazon Cognito 控制台中指定域名，并提供您使用 [AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/)（ACM）管理的证书。在添加域后，Amazon Cognito 提供了一个要添加到 DNS 配置的别名目标。 ## 先决条件 在开始之前，您需要： + 用户池和应用程序客户端。有关更多信息，请参阅 [用户池入门](getting-started-user-pools.md)。 + 您拥有的 Web 域。其*父域*必须具有有效的 DNS **A 记录**。您可以为该记录分配任何值。父域可以是域的根，也可以是域层次结构中上一级的子域。例如，如果您的自定义域是 *auth.xyz.example.com*，Amazon Cognito 必须能够将 *xyz.example.com* 解析为 IP 地址。为了防止对客户基础设施造成意外影响，Amazon Cognito 不支持使用顶级域名 (TLDs) 作为自定义域名。有关更多信息，请参阅[域名](https://tools.ietf.org/html/rfc1035)。 + 能够为自定义域创建子域。建议对您的子域名进行**身份验证**。例如：*auth.example.com*。 **注意** 如果您没有[通配符证书](https://en.wikipedia.org/wiki/Wildcard_certificate)，则可能需要为自定义域的子域获取新证书。 + 由美国东部（弗吉尼亚北部）ACM 管理的公共 SSL/TLS 证书。证书必须在 us-east-1 中，因为该证书将与全球服务中的发行版 CloudFront相关联。 + 支持服务器名称指示（SNI）的浏览器客户端。Amazon Cognito CloudFront 分配给自定义域名的分配需要 SNI。您无法更改此设置。有关 CloudFront 分发中的 SNI 的更多信息，请参阅《*亚马逊 CloudFront 开发者*指南》中的 “[使用 SNI 处理 HTTPS 请求](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-https-dedicated-ip-or-sni.html#cnames-https-sni)”。 + 一个应用程序，允许您的用户池授权服务器向用户会话中添加 Cookie。Amazon Cognito 为托管登录页面设置多个必需的 Cookie。这包括 `cognito`、`cognito-fl` 和 `XSRF-TOKEN`。尽管每个 Cookie 都符合浏览器大小限制，但更改用户池配置可能会导致托管登录 Cookie 变大。像自定义域前面的应用程序负载均衡器（ALB）这样的中间服务可能会强制设定最大请求头大小或总 Cookie 大小。如果您的应用程序还设置了自己的 Cookie，则用户的会话可能会超过这些限制。为避免大小限制冲突，建议您的应用程序不要在托管用户池域服务的子域上设置 Cookie。 + 允许更新 Amazon CloudFront 分配。为此，您可以为 AWS 账户中的用户附加以下 IAM policy 声明： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] } ``` ------ 有关授权操作的更多信息 CloudFront，请参阅[使用基于身份的策略（IAM 策略）](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/access-control-managing-permissions.html)。 CloudFront Amazon Cognito 最初使用您的 IAM 权限来配置 CloudFront分配，但分配由管理。 AWS您无法更改 Amazon Cognito 与您的用户池关联的 CloudFront 分配的配置。例如，您无法更新安全策略中支持的 TLS 版本。 ## 步骤 1：输入自定义域名 您可以使用 Amazon Cognito 控制台或 API 将域添加到用户池。 ------ #### [ Amazon Cognito console ] **将域从 Amazon Cognito 控制台添加到用户池：** 1. 导航到**品牌**下的**域**菜单。 1. 选择**域**旁边的**操作**，然后选择**创建自定义域**或**创建 Amazon Cognito 域**。如果您已配置用户池自定义域，请先选择**删除自定义域**，然后再创建新的自定义域。 1. 选择**域**旁边的**操作**，然后选择**创建自定义域**。如果您已配置自定义域，请先选择**删除自定义域**来删除现有域，然后再创建新的自定义域。 1. 对于**自定义域**，请输入您希望与 Amazon Cognito 一起使用的域的 URL。您的域名只能包含小写字母、数字和连字符。请勿对第一个或最后一个字符使用连字符。使用句点来分隔子域名。 1. 对于 **ACM 证书**，请选择要用于您的域的 SSL 证书。无论您的用户池如何，只有美国东部（弗吉尼亚北部）的 ACM 证书才有资格用于 Amazon Cognito 自定义域。 AWS 区域 如果您没有可用证书，则可以使用 ACM 在美国东部（弗吉尼亚北部）预置一个证书。有关更多信息，请参阅《AWS Certificate Manager 用户指南》**中的[入门](https://docs.aws.amazon.com/acm/latest/userguide/gs.html)。 1. 选择**品牌版本**。您的品牌版本适用于该域的所有用户交互页面。您的用户池可以针对所有应用程序客户端，对托管登录或托管 UI 品牌进行托管。 **注意** 您可以拥有自定义域和前缀域，但是 Amazon Cognito 仅为*自定义*域处理 `/.well-known/openid-configuration` 端点。 1. 选择**创建**。 1. Amazon Cognito 将转至**域**菜单。此时将显示标题为**在域名的 DNS 中创建别名记录**的消息。记下控制台中显示的**域**和**别名目标**。在下一步骤中，将使用它们将流量指向您的自定义域。 ------ #### [ API ] 以下[CreateUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPoolDomain.html)请求正文创建了一个自定义域。 ``` { "Domain": "auth.example.com", "UserPoolId": "us-east-1_EXAMPLE", "ManagedLoginVersion": 2, "CustomDomainConfig": { "CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" } } ``` ------ ## 步骤 2：添加别名目标和子域 在本步骤中，您将通过域名服务器（DNS）服务提供商设置一个别名，该别名指回到上一个步骤中的别名目标。如果您将 Amazon Route 53 用于 DNS 地址解析，请选择**使用 Route 53 添加别名目标和子域**部分。 ### 将别名目标和子域添加到当前 DNS 配置 + 如果您没有将 Route 53 用于 DNS 地址解析，则必须使用您的 DNS 服务提供商配置工具将上一个步骤中的别名目标添加到域 DNS 记录中。您的 DNS 提供商还需要为您的自定义域设置子域。 ### 使用 Route 53 添加别名目标和子域 1. 登录 [Route 53 控制台](https://console.aws.amazon.com/route53/)。如果出现提示，请输入您的 AWS 凭据。 1. 如果您在 Route 53 中没有公共托管区，请创建一个托管区，将根域作为您的自定义域的父域。有关更多信息，请参阅《Amazon Route 53 开发人员指南》**中的[创建公共托管区](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html)。 1. 选择**创建托管区域**。 1. 例如*auth.example.com*，从域名列表中输入自定义域名的父**域名**。*myapp.auth.example.com* 1. 输入托管区域的**描述**。 1. 选择**公有托管区域**的托管区域**类型**以允许公共客户端解析您的自定义域。不支持选择**私有托管区域**。 1. 根据需要应用**标签**。 1. 选择**创建托管区域**。 **注意** 您还可以为自定义域创建新的托管区，并且使用父托管区中的委托集将查询指向子域托管区。否则，请创建 A 记录。此方法为您的托管区域提供了更大的灵活度和安全性。有关更多信息，请参阅[通过 Amazon Route 53 为托管域创建子域](https://aws.amazon.com/premiumsupport/knowledge-center/create-subdomain-route-53/)。 1. 在**托管区域**页面上，选择您的托管区域的名称。 1. 为自定义域的父域添加 DNS 记录（如果您还没有 DNS 记录）。为父域创建 DNS 记录，其属性如下： + **记录名称**：留空。 + **记录类型**：`A`。 + **别名**：不启用。 + **值**：输入您选择的目标。此记录必须解析到*某个地址*，但记录的值对于 Amazon Cognito 来说并不重要。 + **TTL**：设置为您的首选 TTL 或保留为默认值。 + **路由策略**：选择**简单路由**。 1. 选择**创建记录**。以下是该域的示例记录*example.com*： `example.com. 60 IN A 198.51.100.1` **注意** Amazon Cognito 验证您的自定义域的父域是否有 DNS 记录，以防止意外劫持生产域。如果您没有父域的 DNS 记录，则当您尝试设置自定义域时，Amazon Cognito 将返回错误消息。起始授权（SOA）记录是一条 DNS 记录，但不足以用于父域验证。 1. 使用以下属性为您的自定义域添加另一条 DNS 记录： + **记录名称**：用于为 `auth.example.com` 创建记录的自定义域前缀（例如 `auth`）。 + **记录类型**：`A`。 + **别名**：启用。 + **流量路由至**：选择 **CloudFront 分发的别名**。输入您之前记录的**别名目标**，例如 `123example.cloudfront.net`。 + **路由策略**：选择**简单路由**。 1. 选择**创建记录**。 **注意** 新记录可能需要大约 60 秒钟才能传播到所有 Route 53 DNS 服务器。您可以使用 Route 53 [GetChange](https://docs.aws.amazon.com/Route53/latest/APIReference/API_GetChange.html)API 方法来验证您的更改是否已传播。 ## 步骤 3：验证登录页面 + 验证登录页面是否可从您的自定义域访问。 通过在浏览器中输入此地址，使用您的自定义域和子域进行登录。以下是*example.com*带有子域名的自定义网域的网址示例：*auth* ``` https://myapp.auth.example.com/login?response_type=code&client_id=&redirect_uri= ``` ## 更改自定义域的 SSL 证书 如果需要，您可以使用 Amazon Cognito 更改应用于自定义域的证书。 通常，在使用 ACM 进行常规证书续订后，此操作是不必要的。当您续订 ACM 中的现有证书时，证书的 ARN 保持不变，并且您的自定义域将自动使用新证书。 但是，如果您将现有证书替换为新证书，ACM 将为新证书提供一个新 ARN。要将新证书应用于自定义域，您必须将此 ARN 提供给 Amazon Cognito。 在提供新证书后，Amazon Cognito 需要长达 1 小时才能将它分配给自定义域。 **开始前的准备工作** 您必须先将证书添加到 Amazon Cognito，然后才能更改 ACM 中的证书。有关更多信息，请参阅《AWS Certificate Manager 用户指南》**中的[入门](https://docs.aws.amazon.com/acm/latest/userguide/gs.html)。 将您的证书添加到 ACM 时，您必须选择美国东部（弗吉尼亚北部）作为 AWS 区域。 您可以使用 Amazon Cognito 控制台或 API 更改证书。 ------ #### [ AWS 管理控制台 ] **更新 Amazon Cognito 控制台的证书：** 1. 登录 AWS 管理控制台 并打开 Amazon Cognito 控制台，网址为。[https://console.aws.amazon.com/cognito/home](https://console.aws.amazon.com/cognito/home) 1. 选择**用户池**。 1. 选择要更新其证书的用户池。 1. 选择**域**菜单。 1. 选择 **操作**、**编辑 ACM 证书**。 1. 选择您希望与自定义域关联的新证书。 1. 选择**保存更改**。 ------ #### [ API ] **更新证书（Amazon Cognito API）** + 使用 [UpdateUserPoolDomain](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPoolDomain.html) 操作。 ------ # 将品牌应用于托管登录页面 您可能想在身份验证服务和应用程序之间提供一致的用户体验。您可以通过 AWS SDK 中的自定义表单和后端 API 操作或托管登录来实现此目标。托管登录和经典托管 UI 是应用程序中提供用户池身份验证的组件的 Web 前端。要将托管身份验证服务与应用程序 UX 同步，您有两个自定义选项：品牌编辑器和托管 UI 品牌。您可以在 Amazon Cognito 控制台中使用用户池 API 操作来选择自己的首选体验。 **品牌编辑器** [品牌编辑器](managed-login-brandingeditor.md)是[托管登录](cognito-user-pools-managed-login.md)（最新的用户池 UI 体验）的最新自定义选项。品牌编辑器是一个无代码的可视化编辑器，用于管理托管登录页面的资产和样式，同时提供一组 API 操作，支持以编程方式配置大量配置选项。配置了[域](cognito-user-pools-assign-domain.md)和托管登录的用户池会自动呈现品牌设计器版本的登录页面。 **托管 UI（经典）品牌** [托管 UI（经典）品牌体验](hosted-ui-classic-branding.md)有两个选项：修改一个具有固定样式选项的层叠样式表（CSS）文件，以及添加自定义徽标图像。您可以在 Amazon Cognito 控制台中或通过[设置 UICustomization API 操作来设置](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html)这些选项。在该服务推出时，Amazon Cognito 只有这个选项。配置了[域](cognito-user-pools-assign-domain.md)和托管 UI 品牌版本的用户池会自动呈现经典版本的登录页面。您的[功能计划](cognito-sign-in-feature-plans.md)也可能仅支持托管 UI。 **注意** 品牌编辑器和经典品牌体验会修改托管身份验证服务的视觉属性。目前，您无法修改托管登录页面上显示的文本，只能将本地化应用于几种语言中的一种。有关本地化的更多信息，请参阅[托管登录本地化](cognito-user-pools-managed-login.md#managed-login-localization)。 ## 选择品牌体验并分配样式 在 Amazon Cognito 控制台中，新用户池默认为**托管登录**品牌体验。您在托管登录可用之前设置的用户池将显示**托管 UI（经典）**品牌。您可以在托管登录和托管 UI 品牌之间切换。当您更改**品牌版本**时，Amazon Cognito 会立即将更改应用于您的用户池域的用户交互式页面。在托管登录和托管 UI 中，您的用户池可以为每个应用程序客户端设置一种样式。 每个应用程序客户端可以有不同的品牌*样式*，但是一个用户池域只能用于托管登录或托管 UI 中的一种。样式是指应用于应用程序客户端的一组自定义设置。每个用户池可以设置一个[自定义域](cognito-user-pools-add-custom-domain.md)和一个[前缀域](cognito-user-pools-assign-domain-prefix.md)。您可以为自定义域和前缀域分配不同的品牌版本。但是，如果您还有自定义域，则前缀域的功能并不完整：`.well-known` OIDC 发现端点*仅* 提供自定义域的路径。在具有此配置的用户池中，前缀域只能用于不需要端点发现（`openid-configuration`）的操作。由于用户池的这些属性，您在每个用户池中只能有效使用一种品牌样式。 您可以在已将域设置为托管登录品牌版本的用户池中，为应用程序客户端分配样式。样式是一组视觉设置，由图像文件、显示选项和 CSS 值组成。当您为应用程序客户端分配样式后，Amazon Cognito 会立即将您的更新推送到用户交互式登录页面。Amazon Cognito 会使用您选择的品牌版本及其所应用的自定义设置来呈现这些用户交互式页面。 ### 更新和删除样式 创建样式时，可将其链接到应用程序客户端。要更改应用程序客户端的样式分配，必须先删除原始样式。目前，您无法在样式之间复制设置，必须通过编程方式来实现这一点。要在样式和应用程序客户端之间复制设置，请[DescribeManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBranding.html)通过 API 操作获取样式的设置，然后使用[CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)或应用这些设置[UpdateManagedLoginBranding](https://docs.aws.amazon.com/)。您无法更改已分配给应用程序客户端的样式，只能删除原始样式并设置新样式。有关通过 API 和 SDK 操作管理样式的更多信息，请参阅[托管登录品牌的 API 和 SDK 操作](managed-login-brandingeditor.md#branding-designer-api)。 **注意** 对于通过编程方式创建或更新品牌样式的请求，请求大小不得超过 2 MB。如果您的请求超过此限制，请将其拆分为多个 `UpdateManagedLoginBranding` 请求，每组参数的大小均不超过最大请求限制。这些部分更新请求不会将未指定的参数重置为默认值，因此您可以安全地发送它们，而不会影响现有的设置。 您可以在 Amazon Cognito 控制台的**托管登录**菜单中删除样式。在**样式**下，选择要删除的样式，然后选择**删除样式**。 简而言之，为域分配品牌的流程包括以下步骤。 1. [创建域并设置品牌版本](cognito-user-pools-assign-domain.md)。 1. 创建品牌样式，并将其分配给应用程序客户端。 **将样式分配给应用程序客户端** 1. 在用户池的**域**菜单中创建域，并将**品牌版本**设置为**托管登录**。 1. 导航至**托管登录**菜单。在**样式**下，选择**创建样式**。 1. 选择要为其分配样式的应用程序客户端，或新建一个[应用程序客户端](user-pool-settings-client-apps.md)。 1. 要开始配置品牌设置，请选择**启动品牌编辑器**。 **Topics** + [选择品牌体验并分配样式](#managed-login-branding-choose) + [品牌编辑器与自定义托管登录](managed-login-brandingeditor.md) + [自定义托管 UI（经典）品牌](hosted-ui-classic-branding.md) # 品牌编辑器与自定义托管登录 品牌编辑器是托管登录网页的可视化设计和编辑工具。该工具已内置到 Amazon Cognito 控制台中。在品牌编辑器中，您首先会看到登录页面的预览，并可选择进入快速设置选项，或包含高级选项的详细视图。您可以修改和预览样式参数或添加自定义背景图像和徽标。您还可以配置浅色模式和深色模式。 ![\[Amazon Cognito 用户池品牌编辑器可视化编辑器的预览图。\]](http://docs.aws.amazon.com/zh_cn/cognito/latest/developerguide/images/hosted-ui-customization-editor-preview.png) 首先，创建一种可以应用于用户池或应用程序客户端的样式。 **开始使用品牌编辑器** 1. 在**域**选项卡中[创建域](cognito-user-pools-assign-domain.md)，或者更新现有域。在**品牌版本**下，将您的域设置为使用**托管登录**。 1. 如有任何现有应用程序客户端样式，则将其删除。 1. 在**应用程序客户端**菜单中，选择您的应用程序客户端。 1. 在**托管登录样式**下，选择分配给您的应用程序客户端的样式。 1. 选择**删除样式**。确认您的选择。 1. 导航到用户池中的**托管登录**菜单。如果您没有此功能，请按照提示选择一个包含托管登录的[功能计划](cognito-sign-in-feature-plans.md)。如果您只想查看品牌编辑器而不进行任何更改，也可以选择**预览此功能**。 1. 在**样式**下，选择**创建样式**。 1. 选择要为其分配样式的应用程序客户端，然后选择**创建**。您还可以新建应用程序客户端。 1. Amazon Cognito 控制台将启动品牌编辑器。 1. 选择要开始编辑的选项卡，或者选择**启动编辑器**并进入[快速设置](#branding-designer-quick-setup)。可以看到以下选项卡： **预览** 查看您当前的选择在托管登录页面中的实际效果。 **基础** 设置整体主题，配置指向外部身份提供者的链接，并设置表单字段的样式。 **组件** 配置页眉、页脚及各个 UI 元素的样式。 1. 要选择初始设置，请进入快速设置。选择**更改设置类别**，然后选择**快速设置**。选择**继续**后，品牌编辑器将启动，其中包含一组可配置的基本选项。 ## 文本和本地化 您无法在品牌编辑器中修改或本地化文本。请改为在分发给用户的 URL 中添加 `lang` 查询参数。此参数会使您的托管登录页面本地化为多种可用语言之一。有关更多信息，请参阅 [托管登录本地化](cognito-user-pools-managed-login.md#managed-login-localization)。 ## 快速设置 **启动品牌编辑器**按钮会加载一个可视化编辑器，用于配置您的托管登录页面，您可在其中选择多种主要自定义选项。在您进行选择时，Amazon Cognito 会在预览窗口中呈现托管登录页面的更改。要返回详细设置菜单，请选择**更改设置类别**按钮。 **整体外观和风格应该如何？** 为托管登录页面配置基本主题设置。 **显示模式** 为托管登录选择浅色模式、深色模式或自适应体验。自适应设置会在 Amazon Cognito 呈现托管登录页面时，遵循用户的浏览器偏好。当您选择浏览器自适应模式时，可以为浅色模式和深色模式选择不同的颜色和徽标图像。 **Spacing** 设置页面中元素之间的默认间距。 **边框圆角** 设置元素外边框的圆角程度。 **页面背景应呈现什么效果？** **背景类型** **显示图像**复选框用于指定您是希望使用背景图像，还是设置纯色背景。 1. 要使用图像，请选择**显示图像**，然后为浅色模式和深色模式分别选择背景图像。您还可以为图像未覆盖的背景区域分别设置深色模式和浅色模式的**页面背景颜色**。 1. 要使用纯色背景，请取消选择**显示图像**，然后选择浅色模式和深色模式的**页面背景颜色**。 **表单应呈现什么效果？** 为托管登录的表单元素配置设置。表单项的示例包括登录和验证码提示。 **水平对齐** 设置表单字段的水平对齐方式。 **表单徽标** 设置徽标图像的位置。 **徽标图像** 选择要包含在浅色和深色模式的表单元素中的徽标图像文件。要上传图像，请选择**徽标图像**下拉列表，选择**添加新资产**，然后添加徽标文件。 **主要品牌颜色** 为浅色模式和深色模式设置主题颜色。此颜色将作为背景色应用于所有归类为主要元素的元素。 **页眉应呈现什么效果？** 选择是否要在托管登录页面中添加页眉。页眉可以包含徽标图像。 **页眉徽标** 设置徽标图像在页眉中的位置。 **徽标图像** 选择徽标位置，以及要添加在页眉中的徽标图像文件。要上传图像，请选择**徽标图像**下拉列表，选择**添加新资产**，然后添加徽标文件。 **页眉背景颜色** 为页眉的背景设置浅色模式和深色模式颜色。 ## 详细设置 在详细设置视图中，您可以修改**基础**和**组件**中的各个组件。**预览**选项卡会根据当前上下文和您的自定义设置，显示托管登录页面的预览效果。 ![\[托管登录组件详细配置的 AWS 管理控制台 屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/cognito/latest/developerguide/images/hosted-ui-customization-console-preview.png) 要进入组件的可视化编辑器，请在组件对应的磁贴中选择编辑图标。在主题 Studio 编辑器中，您可以使用**更改设置类别**按钮在组件之间切换。 ### 基础 **应用程序样式** 配置托管登录的基本设置。此类别包含整体主题、文本间距以及页眉和页脚的设置。 **显示模式** 为托管登录页面选择浅色模式、深色模式或自适应体验。当您选择浏览器自适应模式时，可以为浅色模式和深色模式选择不同的颜色和徽标图像。 **Spacing** 设置页面中元素之间的默认间距。 **身份验证行为** 为将您的用户连接到外部身份提供商的按钮配置样式（IdPs）。本节包含**域搜索输入**选项，启用后，托管登录会提示用户输入电子邮件地址，并将其与对应的 [SAML 身份提供者标识符](cognito-user-pools-managing-saml-idp-naming.md)进行匹配。 **表单行为** 配置输入表单的样式：输入的位置、颜色和元素的对齐方式。 ### 组件 **按钮** Amazon Cognito 在托管登录页面上呈现的按钮样式。 **分隔线** 托管登录元素之间分隔线和边界的样式，例如输入表单与外部提供商登录选择器之间的分隔。 **下拉菜单** 下拉菜单的样式。 **网页图标** Amazon Cognito 为选项卡和书签图标提供的图像的样式。 **焦点环** 当前选中输入框的高亮样式。 **表单容器** 包围表单的元素的样式。 **全局页脚** Amazon Cognito 在托管登录页面底部显示的页脚样式。 **全局页眉** Amazon Cognito 在托管登录页面顶部显示的页眉样式。 **指示** 错误和成功消息的样式。 **选项控件** 复选框、多选框和其他输入提示的样式。 **页面背景** 托管登录页面整体背景的样式。 **输入** 表单字段输入提示的样式。 **Link** 托管登录页面中超链接的样式。 **页面文本** 页内文本的样式。 **字段文本** 表单输入框周围文本的样式。 ## 托管登录品牌的 API 和 SDK 操作 您还可以使用 API 操作[CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)和将品牌应用于托管登录风格[UpdateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateManagedLoginBranding.html)。这些操作非常适合为另一个应用程序客户端或用户池创建完全相同或稍作修改版的品牌样式。使用 API 操作查询现有样式的托管登录品牌 [DescribeManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBranding.html)，然后根据需要修改输出并将其应用于其他资源。 `UpdateManagedLoginBranding` 操作不会更改您的样式应用到的应用程序客户端。它仅会更新分配给应用程序客户端的现有样式。要完全替换应用程序客户端的样式，请删除现有样式，[DeleteManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DeleteManagedLoginBranding.html)然后使用指定新样式`CreateManagedLoginBranding`。在 Amazon Cognito 控制台中，情况也是如此：必须先删除现有样式，然后创建新样式。 在 API 或 SDK 请求中设置托管登录品牌时，需要将您的设置嵌入到一个 JSON 文件中，并将该文件转换为 `Document` 数据类型。下面提供了关于可添加的图像以及如何生成编程式请求以配置品牌样式的指导。 ### 图像资产 [CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)并[UpdateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateManagedLoginBranding.html)包括一个`Assets`参数。该参数是一个采用 base64 编码二进制格式的图像文件数组。 **注意** 对于通过编程方式创建或更新品牌样式的请求，请求大小不得超过 2 MB。您请求中的资产可能会使请求超过此限制。如果是这种情况，请将其拆分为多个 `UpdateManagedLoginBranding` 请求，每组参数的大小均不超过最大请求限制。这些部分更新请求不会将未指定的参数重置为默认值，因此您可以安全地发送它们，而不会影响现有的设置。 有些资产对您可提交的文件类型有限制。 **** | 资产 | 接受的文件扩展名 | | --- | --- | | FAVICON\$1ICO | ico | | FAVICON\$1SVG | svg | | EMAIL\$1GRAPHIC | png、svg、jpeg | | SMS\$1GRAPHIC | png、svg、jpeg | | AUTH\$1APP\$1GRAPHIC | png、svg、jpeg | | PASSWORD\$1GRAPHIC | png、svg、jpeg | | PASSKEY\$1GRAPHIC | png、svg、jpeg | | PAGE\$1HEADER\$1LOGO | png、svg、jpeg | | PAGE\$1HEADER\$1BACKGROUND | png、svg、jpeg | | PAGE\$1FOOTER\$1LOGO | png、svg、jpeg | | PAGE\$1FOOTER\$1BACKGROUND | png、svg、jpeg | | PAGE\$1BACKGROUND | png、svg、jpeg | | FORM\$1BACKGROUND | png、svg、jpeg | | FORM\$1LOGO | png、svg、jpeg | | IDP\$1BUTTON\$1ICON | ico、svg | SVG 类型的文件支持以下属性和元素。 ------ #### [ Attributes ] ``` accent-height, accumulate, additivive, alignment-baseline, ascent, attributename, attributetype, azimuth, basefrequency, baseline-shift, begin, bias, by, class, clip, clip-path, clip-rule, color, color-interpolation, color-interpolation-filters, color-profile, color-rendering, cx, cy, d, dx, dy, diffuseconstant, direction, display, divisor, dur, edgemode, elevation, end, fill, fill-opacity, fill-rule, filter, filterunits, flood-color, flood-opacity, font-family, font-size, font-size-adjust, font-stretch, font-style, font-variant, font-weight, fx, fy, g1, g2, glyph-name, glyphref, gradientunits, gradienttransform, height, href, id, image-rendering, in, in2, k, k1, k2, k3, k4, kerning, keypoints, keysplines, keytimes, lang, lengthadjust, letter-spacing, kernelmatrix, kernelunitlength, lighting-color, local, marker-end, marker-mid, marker-start, markerheight, markerunits, markerwidth, maskcontentunits, maskunits, max, mask, media, method, mode, min, name, numoctaves, offset, operator, opacity, order, orient, orientation, origin, overflow, paint-order, path, pathlength, patterncontentunits, patterntransform, patternunits, points, preservealpha, preserveaspectratio, r, rx, ry, radius, refx, refy, repeatcount, repeatdur, restart, result, rotate, scale, seed, shape-rendering, specularconstant, specularexponent, spreadmethod, stddeviation, stitchtiles, stop-color, stop-opacity, stroke-dasharray, stroke-dashoffset, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-opacity, stroke, stroke-width, style, surfacescale, tabindex, targetx, targety, transform, text-anchor, text-decoration, text-rendering, textlength, type, u1, u2, unicode, values, viewbox, visibility, vert-adv-y, vert-origin-x, vert-origin-y, width, word-spacing, wrap, writing-mode, xchannelselector, ychannelselector, x, x1, x2, xmlns, y, y1, y2, z, zoomandpan ``` ------ #### [ Elements ] ``` svg, a, altglyph, altglyphdef, altglyphitem, animatecolor, animatemotion, animatetransform, audio, canvas, circle, clippath, defs, desc, ellipse, filter, font, g, glyph, glyphref, hkern, image, line, lineargradient, marker, mask, metadata, mpath, path, pattern, polygon, polyline, radialgradient, rect, stop, style, switch, symbol, text, textpath, title, tref, tspan, video, view, vkern, feBlend, feColorMatrix, feComponentTransfer, feComposite, feConvolveMatrix, feDiffuseLighting, feDisplacementMap, feDistantLight, feFlood, feFuncA, feFuncB, feFuncG, feFuncR, feGaussianBlur, feMerge, feMergeNode, feMorphology, feOffset, fePointLight, feSpecularLighting, feSpotLight, feTile, feTurbulence ``` ------ ### 托管登录品牌操作的工具 对于托管登录品牌设置对象，Amazon Cognito 管理有一个 [JSON Schema 格式](https://json-schema.org/docs)的文件。以下是以编程方式更新品牌样式的步骤。 **在用户池 API 中更新品牌** 1. 在 Amazon Cognito 控制台中，从用户池的**托管登录**菜单中创建默认的托管登录品牌样式。将其分配给应用程序客户端。 1. 记录您为其创建样式的应用程序客户端的 ID，例如 `1example23456789`。 1. 使用设置为的 [DescribeManagedLoginBrandingByClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeManagedLoginBrandingByClient.html)API 请求检索品牌风格的`ReturnMergedResources`设置`true`。以下是一个示例 请求正文。 ``` { "ClientId": "1example23456789", "ReturnMergedResources": true, "UserPoolId": "us-east-1_EXAMPLE" } ``` 1. 使用您的自定义设置修改 `DescribeManagedLoginBrandingByClient` 的输出。 1. 响应正文包裹在一个 `ManagedLoginBranding` 元素中，该元素不属于创建和更新操作的语法部分。需要移除这个 JSON 对象的顶层结构。 1. 要替换图像，请将 `Bytes` 值替换为每个图像文件的 Base64 编码二进制数据。 1. 要更新设置，请修改 `Settings` 对象的输出，并将其包含在下一次请求中。Amazon Cognito 会忽略 `Settings` 对象中任何未包含在 API 响应所返回的架构中的值。 1. 在[CreateManagedLoginBranding](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateManagedLoginBranding.html)或[UpdateManagedLoginBranding](https://docs.aws.amazon.com/)请求中使用更新的响应正文。如果请求大小超过 2 MB，请将其拆分为多个请求。这些操作采用 `PATCH` 模式，除非您另行指定，否则原始设置将保持不变。 # 自定义托管 UI（经典）品牌 您可以使用 AWS 管理控制台、 AWS CLI 或 API 为托管 UI 指定经典自定义设置。您可以上传要显示在应用程序中的自定义徽标图像。您还可以将层叠样式表（CSS）选项应用于 UI 的外观。 您可以自定义 UI 默认设置，并通过特定设置覆盖各个[应用程序客户端](cognito-terms.md#term-appclient)的设置。Amazon Cognito 会将默认配置应用于所有没有客户端级设置的应用程序客户端。 在 Amazon Cognito 控制台和 API 请求中，用于设置 UI 自定义的请求大小不得超过 135 KB。在极少数情况下，请求标头、您的 CSS 文件和徽标的大小总和可能超过 135 KB。Amazon Cognito 对图像文件进行 Base64 编码。这会将 100KB 大小的图像增加到 130KB，保留 5KB 用于请求标头和 CSS。如果请求太大， AWS 管理控制台 或您的 `SetUICustomization` API 请求将返回`request parameters too large`错误。请将您的徽标图像调整为不超过 100 KB，将 CSS 文件调整为不超过 3 KB。您无法单独设置 CSS 和徽标定制设置。 **注意** 要自定义 UI，必须为用户池设置域。 ## 在经典品牌中指定自定义徽标 Amazon Cognito 将您的自定义徽标放在 [登录端点](login-endpoint.md) 的输入字段上方居中。 为自定义托管 UI 徽标选择可缩放至 350 x 178 像素的 PNG、JPG 或 JPEG 文件。徽标文件的大小不得超过 100KB，或者在 Amazon Cognito 编码为 Base64 之后不超过 130KB。要在 API `ImageFile` [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html)中设置，请将您的文件转换为 Base64 编码的文本字符串，或者在中提供文件路径并让 Amazon Cognito 为您对其进行编码。 AWS CLI ## 在经典品牌中指定 CSS 自定义项 您可以为托管应用程序页面自定义 CSS，但存在以下限制： + 您可以使用以下任意 CSS 类名： + `background-customizable` + `banner-customizable` + `errorMessage-customizable` + `idpButton-customizable` + `idpButton-customizable:hover` + `idpDescription-customizable` + `inputField-customizable` + `inputField-customizable:focus` + `label-customizable` + `legalText-customizable` + `logo-customizable` + `passwordCheck-valid-customizable` + `passwordCheck-notValid-customizable` + `redirect-customizable` + `socialButton-customizable` + `submitButton-customizable` + `submitButton-customizable:hover` + `textDescription-customizable` + 属性值可以包含 HTML，但以下值除外：`@import`、`@supports`、`@page` 或者 `@media` 语句以及 Javascript。 您可以自定义以下 CSS 属性。 **标签** + **font-weight** 是 100 的倍数 (从 100 到 900)。 + **color** 是文本颜色。必须是[合法的 CSS 颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。 **输入字段** + **width** 是以占包含块大小的百分比形式表示的宽度。 + **height** 是输入字段的高度，以像素 (px) 为单位。 + **color** 是文本颜色。它可以是任何标准 CSS 颜色值。 + **background-color** 是输入字段的背景色。它可以是任何标准 CSS 颜色值。 + **border** 是标准 CSS 边框值，用于指定您的应用程序窗口边框的宽度、透明度和颜色。宽度可以是从 1px 到 100px 的任何值。透明度可以是完全透明或不透明。颜色可以是任何标准颜色值。 **文本描述** + **padding-top** 是文本描述上方的填充量。 + **padding-bottom** 是文本描述下方的填充量。 + **display** 可以是 `block` 或 `inline`。 + **font-size** 是文本描述的字体大小。 + **color** 是文本颜色。必须是[合法的 CSS 颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。 **提交按钮** + **font-size** 是按钮文本的字体大小。 + **font-weight** 是按钮文本的字体粗细：`bold`、`italic` 或 `normal`。 + **页边距**是一个由四个值组成的字符串，用于指示按钮的上边距、右边距、下边距和左边距大小。 + **font-size** 是文本描述的字体大小。 + **width** 是按钮文本的宽度，以占包含块大小的百分比形式表示。 + **height** 是按钮的高度，以像素 (px) 为单位。 + **color** 是按钮文本颜色。它可以是任何标准 CSS 颜色值。 + **background-color** 是按钮的背景色。它可以是任何标准颜色值。 **横幅** + **填充**是一个由四个值组成的字符串，用于指示横幅的上边距、右边距、下边距和左边距大小。 + **background-color** 是横幅的背景色。它可以是任何标准 CSS 颜色值。 **提交按钮悬停** + **color** 是您将鼠标指针悬停在按钮上方时按钮的前景色。它可以是任何标准 CSS 颜色值。 + **background-color** 是您将鼠标指针悬停在按钮上方时按钮的背景色。它可以是任何标准 CSS 颜色值。 **身份提供商按钮悬停** + **color** 是您将鼠标指针悬停在按钮上方时按钮的前景色。它可以是任何标准 CSS 颜色值。 + **background-color** 是您将鼠标指针悬停在按钮上方时按钮的背景色。它可以是任何标准 CSS 颜色值。 **密码校验无效** + **color** 是 `"Password check not valid"` 消息的文本颜色。它可以是任何标准 CSS 颜色值。 **背景** + **background-color** 是应用程序窗口的背景色。它可以是任何标准 CSS 颜色值。 **错误消息** + **页边距**是一个由四个值组成的字符串，用于指示上边距、右边距、下边距和左边距大小。 + **padding** 是边距大小。 + **font-size** 是字体大小。 + **width** 是错误消息的宽度，以占包含块大小的百分比形式表示。 + **background** 是错误消息的背景色。它可以是任何标准 CSS 颜色值。 + **边框**是一个由三个值组成的字符串，用于指定边框的宽度、透明度和颜色。 + **color** 是错误消息文本颜色。它可以是任何标准 CSS 颜色值。 + **box-sizing** 用于向浏览器指示应包含的大小属性 (宽度和高度)。 **身份提供商按钮** + **height** 是按钮的高度，以像素 (px) 为单位。 + **width** 是按钮文本的宽度，以占包含块大小的百分比形式表示。 + **text-align** 是文本对齐设置。它可以是 `left`、`right` 或 `center`。 + **margin-bottom** 是下边距设置。 + **color** 是按钮文本颜色。它可以是任何标准 CSS 颜色值。 + **background-color** 是按钮的背景色。它可以是任何标准 CSS 颜色值。 + **border-color** 是按钮边框的颜色。它可以是任何标准 CSS 颜色值。 **身份提供商描述** + **padding-top** 是描述上方的填充量。 + **padding-bottom** 是描述下方的填充量。 + **display** 可以是 `block` 或 `inline`。 + **font-size** 是描述的字体大小。 + **color** 是 IdP 区域标题的文本颜色，例如**使用您的企业账号登录**。必须是[合法的 CSS 颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。 **法律文本** + **color** 是文本颜色。它可以是任何标准 CSS 颜色值。 + **font-size** 是字体大小。 自定义 **Legal text**（法律文本）时，您自定义的是 **We won't post to any of your accounts without asking first**（如果未先询问，我们不会发布到您的任何账户）的消息，该消息显示在登录页面的社交身份提供商下方。 **Logo** + **max-width** 是以占包含块大小的百分比形式表示的最大宽度。 + **max-height** 是以占包含块大小的百分比形式表示的最大高度。 + **background-color** 是包含透明区域的日志背景颜色。必须是[合法的 CSS 颜色值](https://www.w3schools.com/cssref/css_colors_legal.php)。 **输入字段聚焦** + **border-color** 是输入字段的颜色。它可以是任何标准 CSS 颜色值。 + **outline** 是输入字段的边框宽度 (以像素为单位)。 **社交按钮** + **height** 是按钮的高度，以像素 (px) 为单位。 + **text-align** 是文本对齐设置。它可以是 `left`、`right` 或 `center`。 + **width** 是按钮文本的宽度，以占包含块大小的百分比形式表示。 + **margin-bottom** 是下边距设置。 **密码校验有效** + **color** 是 `"Password check valid"` 消息的文本颜色。它可以是任何标准 CSS 颜色值。 ## 使用经典品牌自定义托管用户界面 AWS 管理控制台 您可以使用为您的应用程序指定界面自定义设置。 AWS 管理控制台 **注意** 通过利用您的用户池的特定信息构建以下 URL 并将它键入到浏览器中，您可以查看具有自定义项的托管 UI：` https:///login?response_type=code&client_id=&redirect_uri=` 在控制台中进行的更改出现之前，您可能必须等待长达 1 分钟才能刷新浏览器。 您的域显示在 **App integration**（应用程序集成）选项卡中，该选项卡位于 **Domain**（域）下方。您的应用程序客户端 ID 和回调 URL 在 **App clients**（应用程序客户端）下显示。 **指定应用程序 UI 自定义设置** 1. 登录 [Amazon Cognito 控制台](https://console.aws.amazon.com/cognito/home)。 1. 在导航窗格中，选择 **User Pools**（用户池），然后选择要编辑的用户池。 1. 在**域**选项卡中[创建域](cognito-user-pools-assign-domain.md)，或者更新现有域。在**品牌版本**下，将您的域设置为使用**托管 UI（经典）**。 1. 选择**托管登录**菜单。 1. 要为所有应用程序客户端自定义 UI 设置，请找到**托管 UI 设置**下的**样式**，然后选择**编辑**。 1. 要为某个应用程序客户端自定义 UI 设置，请转到**应用程序客户端**菜单，选择要修改的应用程序客户端，然后找到**托管 UI（经典）样式**并选择**覆盖**。选择**编辑**。 1. 要上载自己的徽标图像文件，请选择 **Choose file**（选择文件）或 **Replace current file**（替换当前文件）。 1. 要自定义托管 UI CSS，请下载 **CSS template.css**，然后使用您想要自定义的值修改模板。只有模板中包含的密钥才能与托管 UI 一起使用。添加的 CSS 密钥不会反映在您的 UI 中。自定义 CSS 文件后，请选择 **Choose file**（选择文件）或 **Replace current file**（替换当前文件）来上载您的自定义 CSS 文件。 ## 使用用户池 API 中的经典品牌自定义托管用户界面，并使用 AWS CLI 使用以下命令可为您的用户池指定应用程序 UI 自定义项。 **使用以下 API 操作，获取用户池的内置应用程序 UI 的 UI 定制设置。** + AWS CLI: `aws cognito-idp get-ui-customization` + AWS API: [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUICustomization.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetUICustomization.html) **使用以下 API 操作，设置用户池的内置应用程序 UI 的 UI 定制设置。** + AWS CLI 来自图像文件：`aws cognito-idp set-ui-customization --user-pool-id --client-id --image-file fileb://"" --css ".label-customizable{ color: ;}"` + AWS CLI 图像编码为 Base64 二进制文本：`aws cognito-idp set-ui-customization --user-pool-id --client-id --image-file --css ".label-customizable{ color: ;}"` + AWS API: [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUICustomization.html)