将您自己的域用于托管 UI - Amazon Cognito

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

将您自己的域用于托管 UI

设置应用程序客户端后,您可以为用户池配置 Amazon Cognito 托管用户界面和授权服务器终端节点的自定义域。使用自定义域名,用户可以使用您自己的网址而不是默认的 Amazon Cognito 域名登录您的应用程序。使用熟悉的域名,自定义域名可以提高用户对应用程序的信任度,尤其是当根域与托管应用程序的域名匹配时。自定义域名还可以符合组织的安全要求。

自定义域有一些先决条件,包括用户池、应用程序客户端和您拥有的网络域。自定义域名还需要自定义域名的SSL证书,在美国东部 AWS Certificate Manager (弗吉尼亚北部ACM)使用 () 进行管理。Amazon Cognito 会创建一个亚马逊 CloudFront 分配,在传输过程中使用您的ACM证书进行保护,该分配必须是您的自定义域DNS名的别名目标。

这些元素准备就绪后,您可以通过 Amazon Cognito 控制台或将自定义域添加到您的用户池中。API这包括指定域名和SSL证书,然后使用提供的别名目标更新您的DNS配置。进行这些更改后,您可以验证登录页面是否可以在您的自定义域中访问。

将自定义域添加到用户池

要将自定义域添加到您的用户池中,您需要在 Amazon Cognito 控制台中指定域名,并提供您使用 AWS Certificate Manager() ACM 进行管理的证书。在您添加域名后,Amazon Cognito 会提供一个别名目标,您可以将其添加到您的DNS配置中。

先决条件

在开始之前,您需要:

  • 用户池和应用程序客户端。有关更多信息,请参阅 用户池入门

  • 您拥有的 Web 域。其父域名必须具有有效的 DNS A 记录。您可以为该记录分配任何值。父域可以是域的根,也可以是域层次结构中上一级的子域。例如,如果您的自定义域是 auth.xyz.example.com,Amazon Cognito 必须能够将 xyz.example.com 解析为 IP 地址。为了防止对客户基础设施造成意外影响,Amazon Cognito 不支持使用顶级域名 (TLDs) 作为自定义域名。有关更多信息,请参阅域名

  • 能够为自定义域创建子域。我们建议使用 auth 作为子域。例如:auth.example.com.

    注意

    如果您没有通配符证书,则可能需要为自定义域的子域获取新证书。

  • 由管理的安全套接字层 (SSL) 证书ACM。

    注意

    在申请或导入证书之前,您必须在ACM控制台中将 AWS 区域更改为美国东部(弗吉尼亚北部)。

  • 一种允许您的用户池授权服务器向用户会话添加 Cookie 的应用程序。Amazon Cognito 为托管用户界面设置了几个必需的 Cookie。这包括 cognitocognito-flXSRF-TOKEN。尽管每个 Cookie 都符合浏览器大小限制,但更改用户池配置可能会导致托管用户界面 Cookie 的大小变大。像自定义域名前面的 Application Load Balancer (ALB) 这样的中间服务可能会强制规定最大标题大小或总数 Cookie 大小。如果您的应用程序还设置了自己的 Cookie,则用户的会话可能会超过这些限制。为避免大小限制冲突,我们建议您的应用程序不要在托管 UI 子域上设置 Cookie。

  • 允许更新 Amazon CloudFront 分配。为此,您可以将以下IAM策略声明附加到您的 AWS 账户用户:

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowCloudFrontUpdateDistribution", "Effect": "Allow", "Action": [ "cloudfront:updateDistribution" ], "Resource": [ "*" ] } ] }

    有关授权操作的更多信息 CloudFront,请参阅使用基于身份的策略(IAM策略)。 CloudFront

    Amazon Cognito 最初使用您的IAM权限来配置 CloudFront分配,但分配由管理。 AWS您无法更改 Amazon Cognito 与您的用户池关联的 CloudFront 分配的配置。例如,您无法更新安全策略中支持的TLS版本。

步骤 1:输入自定义域名

您可以使用 Amazon Cognito 控制台将您的域添加到您的用户池中,或者。API

Amazon Cognito console
将域从 Amazon Cognito 控制台添加到用户池:
  1. 登录 Amazon Cognito 控制台。如果出现提示,请输入 AWS 凭证。

  2. 选择用户池

  3. 选择要向其添加域的用户池。

  4. 选择应用程序集成选项卡。

  5. 选择在旁边的操作,然后选择创建自定义域

    注意

    如果您已配置用户池域,请先选择删除 Cognito 域删除自定义域来删除现有域,然后再创建新的自定义域。

  6. 对于自定义域名,请输入您要用于 Amazon Cognito 的域名。URL您的域名只能包含小写字母、数字和连字符。请勿对第一个或最后一个字符使用连字符。使用句点来分隔子域名。

  7. 对于ACM证书,请选择要用于您的域的SSL证书。无论您的用户池如何,只有美国东部(弗吉尼亚北部)的ACM证书才有资格用于 Amazon Cognito 自定义域。 AWS 区域

    如果您没有可用的证书,则可以使用ACM在美国东部(弗吉尼亚北部)配置一个证书。有关更多信息,请参阅《AWS Certificate Manager 用户指南》中的入门

  8. 选择创建

  9. Amazon Cognito 将您返回到应用程序集成选项卡。屏幕上会显示一条标题为 “在您的域名中创建别名记录” DNS 的消息。记下控制台中显示的别名目标。在下一步骤中,将使用它们将流量指向您的自定义域。

API
要使用 Amazon Cognito API 将您的域名添加到您的用户池中,请执行以下操作:

步骤 2:添加别名目标和子域

在此步骤中,您将通过域名服务器 (DNS) 服务提供商设置一个别名,该别名指向上一步中的别名目标。如果您使用 Amazon Route 53 进行DNS地址解析,请选择 “使用 Route 53 添加别名目标和子域” 部分。

  • 如果您未使用 Route 53 进行DNS地址解析,则必须使用DNS服务提供商的配置工具将上一步中的别名目标添加到域的DNS记录中。您的DNS提供商还需要为您的自定义域名设置子域名。

  1. 登录 Route 53 控制台。如果出现提示,请输入 AWS 凭证。

  2. 如果您在 Route 53 中没有公共托管区域,请使用您的自定义域的父域的根目录创建一个公共托管区域。有关更多信息,请参阅 Amazon Route 53 开发者指南中的创建公共托管区域

    1. 选择创建托管区域

    2. 例如,输入父域名 auth.example.com,例如,您的自定义域名 myapp.auth.example.com,来自域名列表。

    3. 输入托管区域的描述

    4. 选择公有托管区域的托管区域类型以允许公共客户端解析您的自定义域。不支持选择私有托管区域

    5. 根据需要应用标签

    6. 选择创建托管区域

      注意

      您也可以为自定义域创建新的托管区域,并在父托管区域中设置委托,将查询定向到子域托管区域。否则,请创建 A 记录。此方法为您的托管区域提供了更大的灵活度和安全性。有关更多信息,请参阅通过 Amazon Route 53 为托管域创建子域

  3. 托管区域页面上,选择您的托管区域的名称。

  4. 如果您还没有,请为自定义域名的父域名添加DNS记录。使用以下属性为父域创建DNS记录:

    • 记录名称:留空。

    • 记录类型:A.

    • 别名:不要启用。

    • :输入您选择的目标。这条记录必须解析为某件事,但是记录的价值对于 Amazon Cognito 来说并不重要。

    • TTL:设置为您的首选TTL或保留为默认值。

    • 路由策略:选择简单路由

  5. 选择创建记录。以下是该域的示例记录 example.com:

    example.com. 60 IN A 198.51.100.1

    注意

    Amazon Cognito 会验证您的自定义域名的父域名是否有DNS记录,以防生产域名被意外劫持。如果您没有父域名的DNS记录,则当您尝试设置自定义域名时,Amazon Cognito 将返回错误。就父域名验证而言,起始权限 (SOA) DNS 记录不足以作为记录。

  6. 使用以下属性为您的自定义域名添加另一DNS条记录:

    • 记录名称:您的自定义域名前缀,例如auth为其创建记录auth.example.com

    • 记录类型:A.

    • 别名:启用。

    • 将流量路由到:选择 Cloudfront 分配的别名。例如,输入您之前录制的别名目标123example.cloudfront.net

    • 路由策略:选择简单路由

  7. 选择创建记录

    注意

    您的新记录可能需要大约 60 秒才能传播到所有 Route 53 DNS 服务器。您可以使用 Route 53 GetChangeAPI方法来验证您的更改是否已传播。

步骤 3:验证登录页面

  • 验证登录页面是否可从您的自定义域访问。

    通过在浏览器中输入此地址,使用您的自定义域和子域进行登录。这是自定义域URL名的示例 example.com 使用子域名 auth:

    https://myapp.auth.example.com/login?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url>

更改自定义域名的SSL证书

如果需要,您可以使用 Amazon Cognito 更改应用于自定义域的证书。

通常,在使用进行例行证书续订后,这是不必要的ACM。在中续订现有证书时ACM,您的ARN证书将保持不变,并且您的自定义域会自动使用新证书。

但是,如果您用新证书替换现有证书,则会为新证书ACM提供一个新证书ARN。要将新证书应用于您的自定义域名,您必须将其提供ARN给 Amazon Cognito。

在提供新证书后,Amazon Cognito 需要长达 1 小时才能将它分配给自定义域。

开始前的准备工作

在 Amazon Cognito 中更改证书之前,必须先将证书添加到。ACM有关更多信息,请参阅《AWS Certificate Manager 用户指南》中的入门

将证书添加到时ACM,必须选择美国东部(弗吉尼亚北部)作为 AWS 区域。

您可以使用 Amazon Cognito 控制台更改证书,或者。API

AWS Management Console
更新 Amazon Cognito 控制台的证书:
  1. 登录 AWS Management Console 并打开 Amazon Cognito 控制台,网址为。https://console.aws.amazon.com/cognito/home

  2. 选择用户池

  3. 选择要更新其证书的用户池。

  4. 选择应用程序集成选项卡。

  5. 选择操作编辑ACM证书

  6. 选择您希望与自定义域关联的新证书。

  7. 选择 Save changes(保存更改)

API
续订证书 (Amazon CognitoAPI)