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

Short description

If your API clients are geographically dispersed, then use an edge-optimized API endpoint in API Gateway. This type of endpoint acts as a Regional endpoint with an AWS managed CloudFront web distribution to improve client connection time.

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

Resolution

Prerequisites: Create an AWS Lambda function to integrate with your API Gateway REST API, and create a Regional API in API Gateway.

Create an SSL/TLS certificate in AWS Certificate Manager (ACM) in the us-east-1 Region and in the same AWS Region as your API Gateway REST API. To get a certificate for a domain name that's issued by or imported into ACM, register your internet domain. You can use either Amazon Route 53 or a third-party accredited domain registrar. Then, create an SSL/TLS certificate for the domain name in ACM, or import one into ACM.

Set up a GET method for your API

Complete the following steps:

1. Open the API Gateway console.
2. Choose the name of your new Regional API.
3. Choose Create resource.
4. For Resource name, enter greetings.
5. Choose Create method.
6. Choose GET for Method type, and select Lambda Function for Integration type. Then, toggle the Lambda proxy integration button and select your Lambda function.

Deploy your API and identify your API invoke URL

Complete the following steps:

1. Deploy your API to a stage.
2. At the head of the Stage Editor pane, copy the Invoke URL for the GET HTTP method of the greetings resource to your clipboard.

See the following API Gateway API invoke URL example: https://restApiId.execute-api.region.amazonaws.com/stageName/greetings

Test your API for a 200 OK response

To confirm that your API returns a "200 OK" response, test your API invoke URL through the API Gateway console. You can also use the Postman app on the Postman website, or curl on the curl website.

Use curl to test your API for a 200 OK response

For Linux, run the following command:

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

Note: Replace https://restApiId.execute-api.region.amazonaws.com/stageNamee/greetings with your API invoke URL.

For Windows PowerShell, run the following command:

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

Note: If you get a status code other than "200 OK", then check the console to confirm that your API is deployed to your stage. Also, confirm that your invoke URL correctly specifies your stage.

Create a CloudFront web distribution

Complete the following steps:

1. Open the CloudFront console.
2. Choose Create Distribution.
3. For Origin Domain Name, enter your API invoke URL. For example, https://restApiId.execute-api.region.amazonaws.com. Then, delete the stage and resource name.
4. For Protocol, select HTTPS Only.
   Note: API Gateway doesn't support unencrypted (HTTP) endpoints. For more information, see Amazon API Gateway FAQs.
5. For Minimum Origin SSL Protocol, choose TLSv1.2.
   Note: Don't choose SSLv3. API Gateway doesn't support the SSLv3 protocol.
6. For Origin Path, enter your API stage name with a slash in front of it (/stageName). Or, to enter the stage name yourself when you invoke the URL, keep Origin Path blank.
   Note: If you enter an incorrect stage name for Origin Path and then invoke the CloudFront distribution, then you might get an error. For example, you might get an unauthorized request error that returns a "Missing Authentication Token" error and a "403 Forbidden response" error.
7. (Optional) To forward custom headers to your origin, enter one or more custom headers for Origin Custom Headers. Follow the instructions in the Configure IAM Authentication and custom domain names to your distribution section.
8. (Optional) Under Distribution Settings, configure the additional settings that you want to customize.
9. Choose Create Distribution.
10. Wait 15-20 minutes for your distribution to deploy. When the distribution Status appears as Deployed in the console, the distribution is ready.

For more information, see Create a distribution.

Test your CloudFront web distribution

Complete the following steps:

1. Open the CloudFront console.
2. Copy the Distribution domain name of your distribution to your clipboard. The following is an example of a non-custom domain name: a222222bcdefg5.cloudfront.net
3. Test the domain name for a "200 OK" response. If you get a "500 server error", then the distribution might not be deployed. If you get no response, then the CloudFront DNS record hasn't propagated yet. In either case, wait 15-20 minutes after you create your distribution, and then retry the procedure.

Important: The preceding steps are for API resources that don't have AWS Identity and Access Management (IAM) authentication turned on for any of the resource methods. If you have methods with IAM authentication, then append the resource name to the end of the distribution domain name when you invoke your API. The full invoke URL looks similar to one of the following examples.

API Gateway API invoke URL with an origin path defined in CloudFront: https://distributionDomainName/resourceName

API Gateway API invoke URL without an origin path defined in CloudFront: https://distributionDomainName/stageName/resourceName

For more information on how to test your distribution, see How do I activate IAM authentication for API Gateway REST APIs?

Configure IAM authentication and custom domain names to your distribution

Note: By default, CloudFront doesn't forward incoming Authorization headers to the origin. If you use IAM authentication for your API or custom domain names for your distribution, then take one of the following actions.

Add the Authorization header to your CloudFront allowlist (For IAM authentication)

Complete the following steps:

1. Create a CloudFront distribution.
2. On the Create Distribution page, for Default cache behavior and Cache key and origin requests, select Legacy cache settings.
3. Choose Include the following headers on the Headers dropdown list. Then, select Authorization from the list of headers that appear. Configure the headers that you want to be forwarded to your API.
4. For Cache key and origin requests, under Cache Policy, choose either an existing cache policy or create a new cache policy. The policy must add the Authorization header to your CloudFront allowlist.
5. (Optional) To test the setup, create the required AWS 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. See the following API Gateway invoke URL example: example_api_id.execute.example_region.amazon.com. Also, see the following CloudFront web distribution URL example: d######.cloudfront.net

Note: If you use the Postman app, then in the Authorization tab, for Type, choose AWS Signature. Then, enter the Access Key and Secret Key. Postman uses the credentials that you enter to generate the required headers. Then, use the Authorization header and all SignedHeaders generated from the SigV4 process to send the API request to the CloudFront distribution.

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

Complete the following steps:

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. For Origin Domain Name, enter your API Gateway target domain name instead of your API invoke URL.
   Note: Find your API Gateway target domain name in the Endpoint configuration section of your custom domain details.
   Example of an API Gateway target domain name: d-######.execute-api.example-region.amazonaws.com
4. On the Create Distribution page, for Default cache behavior and Cache key and origin requests, select Legacy cache settings.
5. Choose Include the following headers on the Headers dropdown list. Then, select the Host and Authorization from the list of headers that appear. Configure the headers that you want to be forwarded to your API.
6. For Cache key and origin requests, under Cache Policy, choose an existing cache policy or create a new cache policy. The policy must add the Authorization header to your CloudFront allowlist.
7. Under Distribution Settings, for Alternate domain name, enter the custom domain name that you created.
8. For SSL Certificate, select Custom SSL Certificate. Then, add the ACM certificate for that domain.
9. After you deploy the CloudFront web distribution, configure the DNS Record to map the custom domain to the CloudFront web distribution. To do this, create either an alias or CNAME record. For more information, see Use custom URLs by adding alternate domain names (CNAMEs).
10. (Optional) To test the setup, create a SigV4 signed request for your custom domain name programmatically.
    Note: To test the setup, you can use the Postman app on the Postman website.

Verify that only requests made through CloudFront reach API Gateway

Complete the following steps:

1. Turn off the API Gateway execution URL from the API settings in the API Gateway console.
2. Create a customer domain name for your API Gateway, and then use the API Gateway target domain name as the origin in CloudFront.
3. Map the custom domain name to the CloudFront web distribution.
   Note: Refer to step 9 of the Set up a Regional custom domain name in API Gateway to access your API section.