Configuring Zuplo with AWS WAF + Shield

AWS WAF + Shield run at AWS CloudFront edge locations. Zuplo can be configured to run as a custom backend behind CloudFront.

Securing Zuplo from Direct Access

With any WAF product, you will want to ensure that network traffic can't bypass your WAF and hit your API Gateway directly. AWS WAF + Shield offer several ways to ensure that your API Gateway is only accessible through the WAF.

The information below is a summary of Amazon's own recommendations for securing your backend - regardless of whether you are using Zuplo, another API Gateway, or AWS origins. You can also reference the AWS documentation directly.

IP Address Restrictions

Amazon maintains a list of CloudFront IP addresses (separate from other AWS uses) that you can use to restrict access to your API Gateway. This is a good way to ensure that only CloudFront can access your API Gateway. However, as CloudFront is available to any AWS customer, this method isn't sufficient to protect unauthorized traffic from hitting your API Gateway.

In Zuplo, you can use the custom IP Restriction policy to limit traffic to only the CloudFront IP addresses. Copy the policy code from that page into a module in your project (for example, modules/ip-restriction-inbound.ts), then configure the policy with the CLOUDFRONT ranges from the AWS IP address ranges list.

Code
{
  "name": "allow-cloudfront-only",
  "policyType": "ip-restriction-inbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/ip-restriction-inbound)",
    "options": {
      "allowedIpAddresses": ["13.32.0.0/15", "13.35.0.0/16"]
    }
  }
}

With this policy in place, only CloudFront traffic will be allowed to hit your Zuplo API Gateway.

Custom Headers

Another way to ensure that traffic is coming from CloudFront is to use custom headers. Custom headers can be added to your CloudFront distribution and then checked by your API Gateway. This provides an additional layer of security on top of IP address restrictions and prevents any unauthorized traffic from hitting your API Gateway - regardless of the source.

In Zuplo, you can use a small custom code policy to limit traffic to only those requests that include the custom header and secret value.

modules/require-secure-header.ts
import {
  environment,
  HttpProblems,
  ZuploContext,
  ZuploRequest,
} from "@zuplo/runtime";

export default async function policy(
  request: ZuploRequest,
  context: ZuploContext,
) {
  const headerValue = request.headers.get("secure-header");
  if (!headerValue || headerValue !== environment.MY_SECRET_HEADER_VALUE) {
    return HttpProblems.unauthorized(request, context);
  }
  return request;
}

Code
{
  "name": "allow-cloudfront-custom-header",
  "policyType": "custom-code-inbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/require-secure-header)"
  }
}

With this policy in place, only requests that include the custom header with the secret value will be allowed to hit your Zuplo API Gateway.

Identity Based Options

Unfortunately, AWS WAF + Shield don't offer identity-based options like IAM or network based options for securing your API Gateway. This is true for both AWS and non-AWS API Gateway products. If you require these options, you will need to use a different WAF product in front of your Zuplo API Gateway.