如何排查在 Amazon Cognito 中创建自定义域时出现的错误？

2 分钟阅读

我需要了解如何解决在 Amazon Cognito 中配置自定义域时出现的常见错误。

简短描述

在 Amazon Cognito 中配置自定义域名时，通常会出现以下错误：

“Custom domain is not a valid subdomain: Was not able to resolve the root domain, please ensure an A record exists for the root domain.（自定义域为无效子域：无法解析根域，请确保根域存在 A 记录。）”
“Domain already associated with another user pool.（域已与其他用户群体关联。）”
“One or more of the CNAMEs you provided are already associated with a different resource.（您提供的一个或多个 CNAME 已与其他资源关联。）”
“The specified SSL certificate doesn't exist, isn't in us-east-1 region, isn't valid, or doesn't include a valid certificate chain.（指定的 SSL 证书不存在、不在 us-east-1 区域中、无效或未包含有效的证书链。）”
“The domain name contains an invalid character.Domain names can only contain lower-case letters, numbers, and hyphens.Please enter a different name that follows this format: ^a-z0-9?$（域名包含无效字符。域名只能包含小写字母、数字和连字符。请输入遵循以下格式的其他名称：^a-z0-9?$）”

解决方法

自定义域不是有效的子域错误

为防止意外更改基础设施，Amazon Cognito 不支持自定义域使用顶级域名（TLD）。要创建 Amazon Cognito 自定义域，父域必须具有域名系统（DNS）A 记录。

父域可能是域的根域，也可以是域层次结构中上一级的子域。例如，如果您的自定义域是 auth.xyz.yourdomain.com，则 Amazon Cognito 必须把 **xyz.**yourdomain.com 解析到 IP 地址上。同样，要把 xyz.yourdomain.com 配置为自定义域，则为 yourdomain.com 配置 A 记录。

您必须在 DNS 配置中为父域创建 A 记录。当父域解析为有效的 A 记录时，Amazon Cognito 不会执行其他验证。如果父域不指向真实 IP 地址，则考虑在 DNS 配置中放置一个虚拟 IP，例如“8.8.8.8”。

您的 DNS 提供商可能需要一些时间才能传播您所做的 DNS 配置更改。要确保您的 DNS 提供商传播了更改，请运行以下任意一条命令。

使用 auth.xyz.yourdomain.com 作为自定义域：

$ dig A xyz.yourdomain.com +short

-或者-

使用 xyz.yourdomain.com 作为自定义域：

$ dig A yourdomain.com +short

**注意：**上述示例命令适用于 Linux 环境。

如果 DNS 配置更改得以传播，则前面的命令将返回您配置的 IP 地址。如果 DNS 查找未返回配置的 IP 地址，则等到更改成功传播。否则，您会不断收到“custom domain is not a valid subdomain（自定义域为无效子域）”错误。

在 Amazon Cognito 中创建自定义域后，您可以移除之前配置的父域 A 记录映射。

域已与其他用户群体错误相关联

在所有 AWS 区域的所有 AWS 账户中，自定义域名必须是唯一的。当您为用户群体使用自定义域名时，同一域名不能用于其他任何用户群体。如果要将域名用于另一个用户群体，则必须删除与第一个用户群体关联的自定义域。

删除自定义域后，需要一段时间才能完全解除自定义域与用户群体的关联。如果您在删除后立即尝试为其他用户群体配置该域名，则可能会遇到域关联错误。如果您收到域关联错误，则在为新用户群体设置该域名之前等待 15-20 分钟。

您提供的一个或多个 CNAME 已与其他资源关联的错误

创建自定义域后，Amazon Cognito 使用相同的自定义域名创建 AWS 托管的 Amazon CloudFront 分配。一个域名只能用于一个 CloudFront 分配。如果您在 CloudFront 中使用域名作为备用域，则无法使用现有域名创建自定义域。如果您尝试创建已与 CloudFront 分配关联的自定义域，则会出现 CNAME 关联错误。

您可以通过以下两种方法中的一种来解决此错误：

为 Amazon Cognito 自定义域使用其他域名。
当使用该域作为 Amazon Cognito 自定义域时，停止将该域名用于其他 CloudFront 分配。

指定的 SSL 证书不存在的错误

要创建 Amazon Cognito 自定义域，您必须拥有 us-east-1 AWS 区域的 AWS Certificate Manager（ACM）证书。当您创建自定义域时，Amazon Cognito 会在内部创建 CloudFront 分配。CloudFront 仅在 us-east-1 区域支持 ACM 证书。
配置自定义域时，请确保您选择的证书未过期。
如果您将证书导入 ACM，请确保该证书由公共证书颁发机构（CA）颁发。证书还必须具有正确的证书链。有关更多信息，请参阅将证书导入到 AWS Certificate Manager 中。
证书必须是 2048 位或更小。证书不得有密码保护。
如果 AWS Key Management Service（AWS KMS）策略评估产生显式拒绝语句，您可能会收到 SSL 证书错误。当创建 Amazon Cognito 自定义域的 IAM 用户或角色的某些 AWS KMS 操作被显式拒绝时，会出现此错误。该错误最常见于以下任何被显式拒绝的 AWS KMS 操作：kms:DescribeKey、kms:CreateGrant 或 kms:*。

域名包含无效字符的错误

如果域名包含除小写字母、数字和连字符以外的任何内容，则不接受该域名。首位或末尾不能使用连字符。整个域名的最大长度为 63 个字符，包括点在内。