How do I troubleshoot errors when I create a custom domain in Amazon Cognito?

Short description

When you configure custom domain names in Amazon Cognito, you might get one of the following error messages:

• "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."
• "Domain already associated with another user pool."
• "One or more of the CNAMEs you provided are already associated with a different resource."
• "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."
• "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?$"

Resolution

The custom domain isn't a valid subdomain

To prevent accidental infrastructure changes, Amazon Cognito doesn't support top-level domains for custom domains. To create an Amazon Cognito custom domain, the parent domain must have a DNS A record.

The parent might be either the root of the domain or a child domain that's one step up in the domain hierarchy. For example, if your custom domain is auth.xyz.yourdomain.com, then Amazon Cognito must resolve xyz.yourdomain.com to an IP address. Also, to configure xyz.yourdomain.com as a custom domain, configure an A record for yourdomain.com.

You must create an A record for the parent domain in your DNS configuration. When the parent domain resolves to a valid A record, Amazon Cognito doesn't perform additional verifications. If the parent domain doesn't point to a real IP address, then put a dummy IP address in your DNS configuration, such as "8.8.8.8".

To make sure that your DNS provider propagated the changes that you made to your DNS configuration, run one of the following commands.

Note: The example commands are for a Linux environment.

To use auth.xyz.yourdomain.com as the custom domain, run the following command:

dig A xyz.yourdomain.com +short

To use xyz.yourdomain.com as the custom domain, run the following command:

dig A yourdomain.com +short

If the DNS configuration change propagates, then the previous command returns the IP address that you configured. If the DNS lookup doesn't return the configured IP address, then wait until the change is propagated.

After you create the custom domain in Amazon Cognito, remove the parent domain A record map.

The domain already is associated with another user pool

Custom domain names must be unique across all AWS accounts and in all AWS Regions. If you use a custom domain name for a user pool, then you can't use the same domain name for any other user pool. To use the domain name for another user pool, delete the custom domain that's associated with the first user pool.

After you delete a custom domain, it takes time to fully dissociate the custom domain from the user pool. If you configure the domain name with another user pool immediately after deletion, then you might get the domain association error message.

One of the CNAMEs that you provided is already associated with a different resource

After Amazon Cognito creates a custom domain, Amazon Cognito uses the same custom domain name to create an AWS managed Amazon CloudFront distribution. You can use a domain name with only one CloudFront distribution. If you use a domain name as an alternate domain in CloudFront, then you can't use the existing domain name to create a custom domain. If you try to create a custom domain that's already associated with a CloudFront distribution, then the CNAME association error message appears.

To resolve this issue, use a different domain name for the Amazon Cognito custom domain. Or, when you use the domain as an Amazon Cognito custom domain, don't use the domain name with another CloudFront distribution.

The specified SSL certificate doesn't exist

When you create the custom domain, Amazon Cognito internally creates a CloudFront distribution. CloudFront supports ACM certificates only in the us-east-1 Region. To create an Amazon Cognito custom domain, you must have an AWS Certificate Manager (ACM) certificate in the us-east-1 AWS Region. 

When you configure the custom domain, make sure that the certificate that you select isn't expired.

If you import a certificate into ACM, then make sure that a public certificate authority issues the certificate. The certificate must also have the correct certificate chain. For more information, see Import certificates into AWS Certificate Manager and Requirements for using SSL/TLS certificates with CloudFront.

If an AWS Key Management Service (AWS KMS) policy evaluation results in an explicit deny statement, then you might receive an SSL certificate error message. When certain AWS KMS actions are explicitly denied for the IAM user or role that creates the Amazon Cognito custom domain, you receive the SSL certificate error message. The issue most commonly occurs for the kms:DescribeKey, kms:CreateGrant, or kms:* AWS KMS actions.

The domain name contains an invalid character

A domain name can't contain anything other than lowercase letters, numbers, and hyphens. You can't use a hyphen for the first or last character. The maximum length of the whole domain name is 63 characters.

Related information

Using your own domain for managed login