How do I set up API Gateway with my own CloudFront distribution?

Last updated: 2021-05-18

I want an edge-optimized API endpoint in Amazon API Gateway, but I need more control over the Amazon CloudFront distribution. How do I create and use my own distribution?

Short description

If your API clients are geographically dispersed, consider using an edge-optimized API endpoint in API Gateway. This type of endpoint acts like a regional endpoint, but has an AWS-managed CloudFront web distribution in front of it to help improve the client connection time.

To use the global CloudFront content delivery network and maintain more control over the distribution, you can use a regional API with a custom CloudFront web distribution.

Resolution

Create a regional API in API Gateway. Then, do the following:

Set up a GET method for your API

1.    In the API Gateway console, choose the name of your new regional API.

2.    In the Resources pane, choose Actions. Then, choose Create Method. A list appears under the / resource node.

3.    Choose GET from the list. Then, choose the check mark icon.

4.    In / - GET - Setup, for Integration type, choose Mock. Then, choose Save.
Note: A mock integration responds to any request that reaches it, which helps with testing.

Deploy your API and identify your API's invoke URL

1.    Deploy your API to a stage.

2.    At the top of the Stage Editor pane, copy the Invoke URL to your clipboard.

API Gateway API Invoke URL example

https://restApiId.execute-api.region.amazonaws.com/stageName.

Test your API for a 200 OK response

To confirm that your API returns a 200 OK response, you can test your API's invoke URL using the API Gateway console, the Postman app, or curl.

To test your API for a 200 OK response using curl

Based on your operating system, run one of the following commands:

Note: Replace https://restApiId.execute-api.region.amazonaws.com/stageName with your API's invoke URL before running either of the following commands.

For Linux, run the following command:

curl -IX GET https://restApiId.execute-api.region.amazonaws.com/stageName

For Windows PowerShell, run the following command:

curl https://restApiId.execute-api.region.amazonaws.com/stageName

Note: If you get a status code other than a 200 OK response, check the console to confirm the following:
Your API is deployed to your stage.
Your stage is specified in your invoke URL.

Create a CloudFront web distribution

1.    In the CloudFront console, choose Create Distribution.

2.    On the Select a delivery method for your content page, under Web, choose Get Started.

3.    On the Create Distribution page, for Origin Domain Name, paste your API's invoke URL. Then, delete the stage name.

Origin domain name example

https://1a2bc3d456.execute-api.us-east-1.amazonaws.com

4.    For Origin Path, enter your API's stage name with a slash in front of it (/stageName). Or, if you want to enter the stage name yourself when invoking the URL, don't enter an Origin Path.
Note: If you enter an incorrect stage name for Origin Path, you can get an error when invoking the CloudFront distribution. For example, an unauthorized request error that returns the message "Missing Authentication Token" and a 403 Forbidden response code.

5.    For Minimum Origin SSL Protocol, it's a best practice to choose TLSv1.2 only. Don't choose SSLv3. API Gateway doesn't support the SSLv3 protocol.

6.    For Origin Protocol Policy, choose HTTPS Only.
Note: API Gateway doesn't support unencrypted (HTTP) endpoints. For more information, see Amazon API Gateway FAQs.

7.    (Optional) To forward custom headers to your origin, enter one or more custom headers for Origin Custom Headers.
Note: There are several custom headers that CloudFront can't forward to your origin.

8.    Follow the instructions in the If you're using IAM authentication for your API or custom domain names for your distribution section, if applicable.

9.    (Optional) Under Distribution Settings, configure any additional settings that you want to customize.

10.    Choose Create Distribution.

11.    Wait for your distribution to deploy. This can take 15-20 minutes. When its Status appears as Deployed in the console, the distribution is ready.

For more information, see Creating a distribution.

Test your CloudFront web distribution

1.    In the CloudFront console, copy the Domain Name of your distribution to your clipboard.

Non-custom domain name example

a222222bcdefg5.cloudfront.net.

2.    Test the domain name for a 200 OK response using either of the commands mentioned previously in the Test your API section. If you get a 500 server error code, the distribution might not be deployed. If you get no response, the CloudFront DNS record might not have propagated yet. In either case, confirm that 15-20 minutes have elapsed since you created your distribution. Then, retry the procedure.

Important: If you turned on IAM authentication on a method for a particular API resource, you must append the resource name to the end of the distribution domain name when invoking your API. The full invoke URL (including the resource name) looks like one of the following examples, depending on whether or not you entered an Origin Path when you created the distribution:

API Gateway API invoke URL with an origin path example

https://distributionDomainName/stageName/resourceName

API Gateway API invoke URL without an origin path example

https://distributionDomainName/resourceName

For more information on testing, see How do I enable IAM authentication for API Gateway APIs?

Your API now uses the web distribution that you created. You can access any resources on the API using the CloudFront URL.

If you're using IAM authentication for your API or custom domain names for your CloudFront web distribution

By default, CloudFront doesn't forward incoming Authorization headers to the origin (for this use case, API Gateway). If you're using IAM authentication for your API or custom domain names for your distribution, you must do one of the following:

(For IAM authentication) Add the Authorization header to your CloudFront allow list and replace the header with the origin domain name of your API

1.    If you haven't done so already, follow steps 1-7 in the Create a CloudFront web distribution section of this article.

2.    On the Create Distribution page, for Cache and origin request settings, choose Use a cache policy and origin request policy. Then, under Cache Policy, choose either an existing cache policy or create a new cache policy that adds the Authorization header to your CloudFront allow list.

3.    If you use an existing cache policy, for Cache Based on Selected Request Headers, choose Whitelist. Then, for Whitelist Headers, add Authorization to the list of allowed headers.

Important: If you change the Cache Based on Selected Request Headers setting to All, or if you allow the Host header, then your setup won't work. For more information, see Caching content based on request headers.

4.    (Optional) To test the setup, do the following:
Create the required Signature Version 4 signature for your API Gateway endpoint programmatically. For the host value, enter your API Gateway invoke URL. For the endpoint value, enter your CloudFront web distribution URL.

API Gateway invoke URL example

<api-id>.execute.<region>.amazon.com

CloudFront web distribution URL example

dxxxxx.cloudfront.net

Note: If you're using the Postman app, in the Authorization tab, for Type, make sure that you choose AWS Signature. Then, enter the Access Key and Secret Key. The required headers are generated by Postman using the credentials you enter.

Then, send the API request to the CloudFront distribution using the Authorization header (and all SignedHeaders) generated from the Signature Version 4 process.

(For custom domain names or IAM authentication) Set up a Regional Custom domain name in API Gateway to access your API

1.    Create a new Regional API in API Gateway or change your edge-optimized API Gateway API to a Regional API.

2.    Set up a Regional custom domain name for the API and create an API mapping for your API.
Note: Use this custom domain name when you access your API through CloudFront.

3.    Create a CloudFront web distribution by following the instructions in the Create a CloudFront web distribution section of this article, with one exception. In step 3, for Origin Domain Name, enter your API Gateway target domain name instead of your API's invoke URL.
Note: You can find your API Gateway target domain name in the Endpoint configuration of your custom domain details.

API Gateway target domain name example

d-xxxx..execute-api.<region>.amazonaws.com

4.    On the Create Distribution page, for Cache and origin request settings, choose Use a cache policy and origin request policy. Then, under Cache Policy, choose either an existing cache policy or create a new cache policy that adds the Authorization and Host header to your CloudFront allow list.

5.    If you use an existing cache policy, for Cache Based on Selected Request Headers, choose Whitelist. Then, for Whitelist Headers, add Authorization and Host to the list of allowed headers.

6.    Under Distribution Settings, for Alternate Domain Name, enter the custom domain name that you created.

7.    For SSL Certificate, select Custom SSL Certificate. Then, add the AWS Certificate Manager (ACM) certificate for that domain.

8.    After you deploy your CloudFront web distribution, configure the DNS Record to map the custom domain to the CloudFront web distribution by creating either an alias or CNAME records. For more information, see Using custom URLs for files by adding alternate domain names (CNAMEs).

9.    (Optional) To test the setup, create a Signature Version 4 signed request for your custom domain name programmatically.
Note: You can also use the Postman app to test the setup.