Front-End Web & Mobile

Use a custom domain with AWS AppSync, Amazon CloudFront, and Amazon Route 53

 

Update: AWS AppSync now supports custom domain names as a feature. Visit the blog post that describes the feature, and the documentation for more details.

 

 

Most of the time, AWS AppSync can use any domain name because a user doesn’t type in the name of the GraphQL endpoint—it’s embedded in an app. However, there are cases when a custom domain name is required:

  • Your security policies require a specific Secure Sockets Layer (SSL) certificate to be used.
  • You need to specify an exact hostname to get through a firewall.
  • You’re exposing the GraphQL endpoint as a public data API.

In these cases, you need to configure some additional services so that your service is available with a custom domain name. In the general process, you’ll do the following:

  1. Obtain a wildcard SSL certificate from a certificate authority (CA).
  2. Import the SSL certificate into AWS Certificate Manager (ACM).
  3. Configure Amazon CloudFront with the newly acquired SSL certificate.
  4. Configure Amazon Route 53 to point to the CloudFront distribution.

In this article, we’ll walk through the steps to access an AWS AppSync GraphQL endpoint with a custom domain.

Prerequisites

  1. Acquire a domain name from a DNS registrar.  For the purposes of this walkthrough, we’ll call our domain “sample.app”
  2. Acquire an appropriate SSL certificate for the domain from a CA.  If you want to access the AWS AppSync GraphQL endpoint with the domain name “graphql.sample.app” (as an example), then ensure the SSL certificate that you acquire is a wildcard certificate.
  3. Import the SSL certificate into ACM.  The certificate must be located in the ACM us-east-1 AWS Region, and marked as Issued in the console.  No other AWS Region works in this case.
  4. Provision an AWS AppSync API.  This can be done in any AWS Region.
  5. Record the API URL of the AWS AppSync API:

 

  1. Record the AWS AppSync origin.  This is the host part of the API URL that you recorded in prerequisite 5.  To generate the host part, strip off the leading ‘https://’ and the trailing ‘/graphql’ from the API URL.

Restrictions

You can configure a custom domain for AWS AppSync for all authentication methods except AWS_IAM.  With the instructions in this article it’s possible to configure a custom domain for any of the other authentication mechanisms: OpenID Connect, Amazon Cognito User Pools and an API key.

This workaround will only work for GraphQL queries and mutations. It doesn’t apply to subscriptions as the AppSync SDK or Amplify clients will establish WebSockets or MQTT over WebSockets connections to separate real-time endpoints that will not be reachable through the CloudFront distribution you’ll create on the next step.

If there’s a requirement to have GraphQL subscriptions over CloudFront, you can leverage the WebSocket support in the distribution and use a custom WebSocket client in your application to connect to it following the AppSync real-time client protocol.

CloudFront setup

After you’ve completed the prerequisites, proceed with the CloudFront setup.

  1. Open the Amazon CloudFront console.
  2. Choose Create Distribution.
  3. Choose Web, and then choose Get Started.
  4. Fill in the Origin Settings:
    • Origin Domain Name: Type the AWS AppSync origin name from prerequisite 6

 

  1. Fill out the Distribution Settings form:
    • Alternate Domain Names (CNAMEs): Enter your custom domain names.  If you want to include multiple names (for example, sample.app and graphql.sample.app), then list the additional domain names as well.
    • SSL Certificate: Choose Custom SSL, and then choose your ACM certificate from the drop-down.  If you don’t see the certificate, make sure that it’s in ACM us-east-1 and listed as Issued.

 

  1. Choose Create distribution at the end of the page.
  2. Wait for the distribution to become available before proceeding.  This can take up to 30 minutes.
  3. After the distribution is available, copy the domain name for the distribution.  This is located on the Distributions page of the Amazon CloudFront console.  It ends in .cloudfront.net.

Test that you can access the AWS AppSync endpoint using the CloudFront domain name.  You can do this by using the curl command:

curl https://my-cloudfront-domain.cloudfront.net/graphql
{
    "errors": [ {
        "errorType": "UnauthorizedException",
        "message": "You are not authorized to make this call."
    } ]
}

Route 53 setup

Next, configure Amazon Route 53 for your domain.  Note that you can’t host your DNS elsewhere in this case.  CloudFront and Route 53 work together to provide custom domain support.

  1. Open the Amazon Route 53 console.
  2. Choose Create Hosted Zone.
  3. Type the Domain Name as “sample app” (your domain).

 

  1. Choose Create.
  2. Choose the domian name that you just created.
  3. Choose Create Record Set.
  4. Fill in the form:
    • Type: A – IPv4 Address
    • Alias: Yes
    • Alias Target: Your CloudFront domain name
    • Routing Policy: Simple

 

  1. Choose Save.
  2. Select the NS record set.  Copy the four values that are listed.

  1. Update the name server list for your domain with the four name servers from the NS record set.  You need to do this with the DNS registrar where you purchased the domain.  You might have to remove the trailing ‘.’ when you update the name servers.
  2. It can take some time for DNS propagation to happen (anywhere from 30 minutes to a day).  Ensure that your name servers are updated before continuing.

After the process is complete, you can test your AWS AppSync endpoint again:

curl https://sample.app/graphql
{
    "errors": [ {
        "errorType": "UnauthorizedException",
        "message": "You are not authorized to make this call."
    } ]
}

If you see any errors that indicate a domain problem (for example, host not found or DNS failed), then it’s likely that DNS propagation hasn’t happened properly yet.  DNS propagation is under the control of your DNS registrar.

This article was contributed by Rohan Deshpande.  Rohan is the architect/lead for AWS AppSync and GraphQL, AWS Device Farm, Amazon Pinpoint, AWS SNS, push notifications, AWS mobile SDKs, and AWS Amplify at Amazon Web Services.  You can follow him on Twitter.