Clarification on CloudFront in front of Edge-Optimized API Gateway and Geo Restriction behavior

Thank you for your detailed architectural question. Let me address your points about using a customer-managed CloudFront distribution in front of an Edge-Optimized API Gateway with geo-restriction.

Regarding your request flow:

Your understanding of the basic flow is correct. When you configure geo-restriction on your CloudFront distribution, it evaluates the viewer's location based on their IP address before forwarding allowed requests to the origin. CloudFront determines user location using a third-party database with approximately 99.8% accuracy. If a viewer is in a denied country, CloudFront returns an HTTP 403 (Forbidden) status code without reaching your origin.

About the AWS-managed CloudFront distribution:

When you use an Edge-Optimized API Gateway, AWS does provision a CloudFront distribution in front of it. However, this creates a layered architecture where requests pass through your customer-managed CloudFront distribution first, then through the AWS-managed CloudFront distribution associated with the API Gateway. This double-CloudFront architecture can introduce complexity in terms of caching behavior, header handling, and geographic evaluation.

Architecture considerations:

While it's technically possible to place a customer-managed CloudFront distribution in front of an Edge-Optimized API Gateway, this creates redundancy since Edge-Optimized API Gateway already includes CloudFront capabilities. For scenarios where you need custom CloudFront configurations—such as specific geo-restriction policies, custom caching behaviors, or advanced security features—using a Regional API Gateway as the origin for your customer-managed CloudFront distribution is generally the recommended approach.

With a Regional API Gateway behind your CloudFront distribution, you have a cleaner architecture with a single CloudFront layer where you maintain full control over geo-restriction, caching policies, and other distribution settings. This eliminates the complexity of having two CloudFront distributions in the request path and provides more predictable behavior for your geo-restriction requirements.

Best practices:

For your use case with geo-restriction requirements, consider using a Regional API Gateway as the origin for your customer-managed CloudFront distribution. This architecture gives you complete control over geographic access controls at the CloudFront level while avoiding the potential complications of layered CloudFront distributions. Geographic restrictions apply to an entire CloudFront distribution, and having a single, customer-managed distribution ensures your geo-restriction policies are applied consistently and predictably.

If you need more granular geographic controls beyond country-level restrictions, you might also consider using AWS WAF with geographic match rules in combination with your CloudFront distribution, which can provide additional filtering capabilities and can be combined with other security rules.
Sources
Restrict the geographic distribution of your content - Amazon CloudFront
Security - Amazon CloudFront for Media
Building geolocation verification for iGaming and sports betting on AWS | AWS for Games Blog

Once our CloudFront distribution allows a request based on Geo Restriction, does the AWS-managed CloudFront associated with the Edge-Optimized API Gateway perform any additional country-based evaluation?

No, it does not. According to Amazon API Gateway - Serverless Applications Lens:

Amazon API Gateway Edge-optimized APIs provide a fully managed Amazon CloudFront distribution to optimize access for geographically dispersed consumers.

Fully managed Amazon CloudFront distribution uses the following fixed configurations:

• Origin Protocol Policy: HTTPS only
• Minimum origin SSL protocol: TLSv1.2
• Viewer protocol policy: Redirect to HTTPS

Geographic restrictions are not included; these remain enabled at the customer-managed CloudFront distribution layer.

Is placing a customer-managed CloudFront distribution in front of an Edge-Optimized API Gateway a supported architecture?

While technically possible, AWS does not recommend this approach and instead advises switching to Regional APIs. When you create an edge-optimized API, AWS automatically creates and manages a CloudFront distribution in the background. Because AWS manages this distribution, you cannot customize it directly via the AWS Management Console.

💡Did you know this feature about AWS API Gateway and CloudFront Integration

While edge-optimized API endpoints are recommended when API clients are geographically distributed, combining a regional API with a customer-managed CloudFront distribution is recommended if you require finer control over the distribution while still utilizing the global CloudFront network. Set up API Gateway with a custom CloudFront distribution | AWS re:Post

Are there any documented limitations or best practices for this architecture compared to using a Regional API Gateway behind CloudFront?

1. Double CloudFront hop (performance degradation) Avoid stacking CloudFront on top of edge-optimized endpoints. It adds unnecessary complexity and may even hurt performance due to multiple layers of resolution. Your traffic flows through two CloudFront layers: your custom distribution → AWS-managed distribution → API Gateway, adding unnecessary latency.

2. HTTP header capitalization conflict Edge-optimized APIs capitalize the names of HTTP headers. Regional APIs pass all header names through as-is. When you place custom CloudFront in front of an edge-optimized API, headers may be transformed twice in unpredictable ways, which can break downstream integrations that depend on specific header casing.

3. Cookie ordering conflict CloudFront sorts HTTP cookies in natural order by cookie name before forwarding the request to your origin. With double-CloudFront, this sorting may be applied twice, potentially causing signature validation failures (e.g., with SigV4 or cookie-based auth).

4. No WAF attachment on the inner CloudFront It uses CloudFront distributions, but you can't edit the distribution. Adding Amazon Web Application Firewall (WAF), for example, is not possible. The AWS-managed CloudFront distribution sitting inside the edge-optimized API cannot have WAF attached to it, so you'd only have WAF on the outer layer.

5. Custom domain name scope conflict Any custom domain name that you use for an edge-optimized API applies across all regions. This is in contrast to Regional APIs where custom domain names are region-specific, giving you more flexibility for multi-region deployments with latency-based routing.

API endpoint types for REST APIs in API Gateway - Amazon API Gateway

We have observed inconsistent behavior while using an Edge-Optimized API with this architecture and would like to understand whether this is expected behavior

The inconsistent behavior you're experiencing with Geo Restriction on an Edge-Optimized API is expected and a direct consequence of the double-CloudFront architecture. The inconsistent behavior with CloudFront geographic restrictions could be due to edge location routing: CloudFront routes requests to the nearest edge location, which might not always be in the same country as the user. This could potentially cause discrepancies in how the geographic restriction is applied.

Issue with Geographic Restrictions on CloudFront Distribution | AWS re:Post

or if a Regional API Gateway is the recommended approach when using a customer-managed CloudFront distribution with Geo Restriction.

Yes, definitively. 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.

Set up API Gateway with a custom CloudFront distribution | AWS re:Post