How do I resolve DNS resolution or SSL certificate mismatch errors for my Amazon API Gateway custom domain name?

3 minute read
0

I can't connect to the custom domain name for my API Gateway and receive DNS resolution or SSL certificate mismatch errors.

Resolution

Resolve public API custom domain errors

To connect to a custom domain name for public API Gateway APIs, you must configure Amazon Route 53 to route traffic to an API Gateway endpoint.

If you don't map the DNS records for the custom domain name to the correct API Gateway domain name, then the SSL connection fails. This is because the default *.execute-api.<region>.amazonaws.com certificate is returned instead of the SSL/TLS certificate.

To check whether you correctly mapped the DNS records, run the following command:

nslookup custom-domain-name

Note: Replace custom-domain-name with your custom domain name.

The output returns the API Gateway domain name. Make sure that the custom domain name matches the API Gateway domain name. If you use a Route 53 alias record to map your DNS, then the output returns the IP address. Make sure that the IP address matches the API Gateway domain name IP address.

Resolve private API custom domain errors

To connect to a custom domain name for private API Gateway APIs, you must configure Route 53 to route traffic to a virtual private cloud (VPC) endpoint DNS name.

To check whether you correctly the mapped DNS record, run the following command:

nslookup custom-domain-name

Note: Replace custom-domain-name with your custom domain name.

The output returns the private IP address of the execute-api VPC endpoint. Make sure that the IP address matches the IP address of the VPC endpoint's subnet that you configured with your API Gateway.

Verify that you created a domain name access association between your custom domain name and your execute-api VPC endpoint.

To check whether you created the domain name access association, run the following command:

curl https://custom-domain-name/resource-path

Note: Replace custom-domain-name with your custom domain name and resource-path with your resource path.

If you created the association, then the output returns the response from your integration endpoint. If you didn't create the association, then the SSL connection fails with the "SSL: no alternative certificate subject name matches target host name" error message.

Note: When you configure a custom domain name for a Regional or edge-optimized public API in Route 53, you must create a public hosted zone. For public applications with resources that you want to make available to users, choose a public hosted zone.

When you create a custom domain for a private API, you must create a private hosted zone and attach your client VPC to the hosted zone.

Route 53 uses records to determine where you want to route traffic for your domain. You can choose to use either an alias record or a CNAME record.

Related information

Get certificates ready in AWS Certificate Manager

How can I set up a custom domain name for my API Gateway API?

Migrate a custom domain name to a different API endpoint type in API Gateway

AWS OFFICIAL
AWS OFFICIALUpdated 5 days ago