品牌编辑器与自定义托管登录 - Amazon Cognito
文本和本地化快速设置详细设置API 操作
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

品牌编辑器与自定义托管登录

品牌编辑器是托管登录网页的可视化设计和编辑工具。该工具已内置到 Amazon Cognito 控制台中。在品牌编辑器中，您首先会看到登录页面的预览，并可选择进入快速设置选项，或包含高级选项的详细视图。您可以修改和预览样式参数或添加自定义背景图像和徽标。您还可以配置浅色模式和深色模式。

Amazon Cognito 用户池品牌编辑器可视化编辑器的预览图。

首先，创建一种可以应用于用户池或应用程序客户端的样式。

开始使用品牌编辑器

  1. 在域选项卡中创建域，或者更新现有域。在品牌版本下，将您的域设置为使用托管登录。

  2. 如有任何现有应用程序客户端样式，则将其删除。

    1. 在应用程序客户端菜单中，选择您的应用程序客户端。

    2. 在托管登录样式下，选择分配给您的应用程序客户端的样式。

    3. 选择删除样式。确认您的选择。

  3. 导航到用户池中的托管登录菜单。如果您没有此功能，请按照提示选择一个包含托管登录的功能计划。如果您只想查看品牌编辑器而不进行任何更改，也可以选择预览此功能。

  4. 在样式下，选择创建样式。

  5. 选择要为其分配样式的应用程序客户端，然后选择创建。您还可以新建应用程序客户端。

  6. Amazon Cognito 控制台将启动品牌编辑器。

  7. 选择要开始编辑的选项卡，或者选择启动编辑器并进入快速设置。可以看到以下选项卡：

    预览

    查看您当前的选择在托管登录页面中的实际效果。

    基础

    设置整体主题，配置指向外部身份提供者的链接，并设置表单字段的样式。

    组件

    配置页眉、页脚及各个 UI 元素的样式。

  8. 要选择初始设置，请进入快速设置。选择更改设置类别，然后选择快速设置。选择继续后，品牌编辑器将启动，其中包含一组可配置的基本选项。

文本和本地化

您无法在品牌编辑器中修改或本地化文本。请改为在分发给用户的 URL 中添加 lang 查询参数。此参数会使您的托管登录页面本地化为多种可用语言之一。有关更多信息，请参阅托管登录本地化。

快速设置

启动品牌编辑器按钮会加载一个可视化编辑器，用于配置您的托管登录页面，您可在其中选择多种主要自定义选项。在您进行选择时，Amazon Cognito 会在预览窗口中呈现托管登录页面的更改。要返回详细设置菜单，请选择更改设置类别按钮。

整体外观和风格应该如何？

为托管登录页面配置基本主题设置。

显示模式

为托管登录选择浅色模式、深色模式或自适应体验。自适应设置会在 Amazon Cognito 呈现托管登录页面时，遵循用户的浏览器偏好。当您选择浏览器自适应模式时，可以为浅色模式和深色模式选择不同的颜色和徽标图像。

间距

设置页面中元素之间的默认间距。

边框圆角

设置元素外边框的圆角程度。

页面背景应呈现什么效果？
背景类型

显示图像复选框用于指定您是希望使用背景图像，还是设置纯色背景。

  1. 要使用图像，请选择显示图像，然后为浅色模式和深色模式分别选择背景图像。您还可以为图像未覆盖的背景区域分别设置深色模式和浅色模式的页面背景颜色。

  2. 要使用纯色背景，请取消选择显示图像，然后选择浅色模式和深色模式的页面背景颜色。

表单应呈现什么效果？

为托管登录的表单元素配置设置。表单项的示例包括登录和验证码提示。

水平对齐

设置表单字段的水平对齐方式。

表单徽标

设置徽标图像的位置。

徽标图像

选择要包含在浅色和深色模式的表单元素中的徽标图像文件。要上传图像，请选择徽标图像下拉列表，选择添加新资产，然后添加徽标文件。

主要品牌颜色

为浅色模式和深色模式设置主题颜色。此颜色将作为背景色应用于所有归类为主要元素的元素。

页眉应呈现什么效果？

选择是否要在托管登录页面中添加页眉。页眉可以包含徽标图像。

页眉徽标

设置徽标图像在页眉中的位置。

徽标图像

选择徽标位置，以及要添加在页眉中的徽标图像文件。要上传图像，请选择徽标图像下拉列表，选择添加新资产，然后添加徽标文件。

页眉背景颜色

为页眉的背景设置浅色模式和深色模式颜色。

详细设置

在详细设置视图中，您可以修改基础和组件中的各个组件。预览选项卡会根据当前上下文和您的自定义设置，显示托管登录页面的预览效果。

一张 Amazon Web Services 管理控制台 屏幕截图，展示了托管登录组件的详细配置。

要进入组件的可视化编辑器，请在组件对应的磁贴中选择编辑图标。在主题 Studio 编辑器中，您可以使用更改设置类别按钮在组件之间切换。

基础

应用程序样式

配置托管登录的基本设置。此类别包含整体主题、文本间距以及页眉和页脚的设置。

显示模式

为托管登录页面选择浅色模式、深色模式或自适应体验。当您选择浏览器自适应模式时，可以为浅色模式和深色模式选择不同的颜色和徽标图像。

间距

设置页面中元素之间的默认间距。

身份验证行为

配置用于将用户连接到外部身份提供者（IdP）的按钮的样式。本节包含域搜索输入选项，启用后，托管登录会提示用户输入电子邮件地址，并将其与对应的 SAML 身份提供者标识符进行匹配。

表单行为

配置输入表单的样式：输入的位置、颜色和元素的对齐方式。

组件

按钮

Amazon Cognito 在托管登录页面上呈现的按钮样式。

分隔线

托管登录元素之间分隔线和边界的样式，例如输入表单与外部提供商登录选择器之间的分隔。

下拉菜单

下拉菜单的样式。

网页图标

Amazon Cognito 为选项卡和书签图标提供的图像的样式。

焦点环

当前选中输入框的高亮样式。

表单容器

包围表单的元素的样式。

全局页脚

Amazon Cognito 在托管登录页面底部显示的页脚样式。

全局页眉

Amazon Cognito 在托管登录页面顶部显示的页眉样式。

指示

错误和成功消息的样式。

选项控件

复选框、多选框和其他输入提示的样式。

页面背景

托管登录页面整体背景的样式。

输入

表单字段输入提示的样式。

链接

托管登录页面中超链接的样式。

页面文本

页内文本的样式。

字段文本

表单输入框周围文本的样式。

托管登录品牌的 API 和 SDK 操作

您还可以使用 API 操作 CreateManagedLoginBranding 和 UpdateManagedLoginBranding 将品牌应用于托管登录样式。这些操作非常适合为另一个应用程序客户端或用户池创建完全相同或稍作修改版的品牌样式。您可以使用 DescribeManagedLoginBranding API 操作查询现有样式的托管登录品牌设置，根据需要修改输出，然后将其应用到其他资源上。

UpdateManagedLoginBranding 操作不会更改您的样式应用到的应用程序客户端。它仅会更新分配给应用程序客户端的现有样式。要完全替换应用程序客户端的样式，请使用 DeleteManagedLoginBranding 删除现有样式，然后使用 CreateManagedLoginBranding 分配新样式。在 Amazon Cognito 控制台中，情况也是如此：必须先删除现有样式，然后创建新样式。

在 API 或 SDK 请求中设置托管登录品牌时，需要将您的设置嵌入到一个 JSON 文件中，并将该文件转换为 Document 数据类型。下面提供了关于可添加的图像以及如何生成编程式请求以配置品牌样式的指导。

图像资产

CreateManagedLoginBranding 和 UpdateManagedLoginBranding 包含一个 Assets 参数。该参数是一个采用 base64 编码二进制格式的图像文件数组。

注意

对于通过编程方式创建或更新品牌样式的请求，请求大小不得超过 2 MB。您请求中的资产可能会使请求超过此限制。如果是这种情况，请将其拆分为多个 UpdateManagedLoginBranding 请求，每组参数的大小均不超过最大请求限制。这些部分更新请求不会将未指定的参数重置为默认值，因此您可以安全地发送它们，而不会影响现有的设置。

有些资产对您可提交的文件类型有限制。

资产 接受的文件扩展名
FAVICON_ICO ico
FAVICON_SVG svg
EMAIL_GRAPHIC png、svg、jpeg
SMS_GRAPHIC png、svg、jpeg
AUTH_APP_GRAPHIC png、svg、jpeg
PASSWORD_GRAPHIC png、svg、jpeg
PASSKEY_GRAPHIC png、svg、jpeg
PAGE_HEADER_LOGO png、svg、jpeg
PAGE_HEADER_BACKGROUND png、svg、jpeg
PAGE_FOOTER_LOGO png、svg、jpeg
PAGE_FOOTER_BACKGROUND png、svg、jpeg
PAGE_BACKGROUND png、svg、jpeg
FORM_BACKGROUND png、svg、jpeg
FORM_LOGO png、svg、jpeg
IDP_BUTTON_ICON 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 格式的文件。以下是以编程方式更新品牌样式的步骤。

在用户池 API 中更新品牌

  1. 在 Amazon Cognito 控制台中，从用户池的托管登录菜单中创建默认的托管登录品牌样式。将其分配给应用程序客户端。

  2. 记录您为其创建样式的应用程序客户端的 ID，例如 1example23456789。

  3. 通过 DescribeManagedLoginBrandingByClient API 请求（将 ReturnMergedResources 设置为 true）检索品牌样式的设置。以下是一个示例请求正文。

    {
   "ClientId": "1example23456789",
   "ReturnMergedResources": true,
   "UserPoolId": "us-east-1_EXAMPLE"
}

  4. 使用您的自定义设置修改 DescribeManagedLoginBrandingByClient 的输出。

    1. 响应正文包裹在一个 ManagedLoginBranding 元素中，该元素不属于创建和更新操作的语法部分。需要移除这个 JSON 对象的顶层结构。

    2. 要替换图像，请将 Bytes 值替换为每个图像文件的 Base64 编码二进制数据。

    3. 要更新设置，请修改 Settings 对象的输出，并将其包含在下一次请求中。Amazon Cognito 会忽略 Settings 对象中任何未包含在 API 响应所返回的架构中的值。

  5. 将更新后的响应正文用于 CreateManagedLoginBranding 或 UpdateManagedLoginBranding 请求。如果请求大小超过 2 MB，请将其拆分为多个请求。这些操作采用 PATCH 模式，除非您另行指定，否则原始设置将保持不变。