Enabling CORS for API Gateway HTTP APIs

Question

Pulumi · Accepted Answer

CORS (Cross-Origin Resource Sharing) is a security feature that allows or restricts requests to a web server from a different domain than the one that served the web page. In the context of AWS API Gateway, enabling CORS lets you control how your API responds to cross-origin requests.

For AWS HTTP APIs (which support both RESTful and WebSocket APIs), CORS can be enabled by setting up the appropriate headers in the response returned by the API. This is typically accomplished by adding an `OPTIONS` method to your API resources, which can explicitly return the headers needed to enable CORS.

To enable CORS in an HTTP API using Pulumi, you need to configure an AWS API Gateway instance with the required CORS configuration. Below, I'll show you how to do this with Pulumi and TypeScript. We'll define the headers needed for CORS, create an API Gateway instance, and set up an OPTIONS method for it.

Let's begin with a detailed Pulumi TypeScript program:

```typescript
import * as aws from "@pulumi/aws";

// Creates an HTTP API Gateway to receive requests
const httpApi = new aws.apigatewayv2.Api("httpApi", {
    protocolType: "HTTP",
});

// Define the CORS configuration
const corsConfiguration = {
    allowOrigins: ["https://example.com"],  // List your origins here (the websites allowed to make cross-origin requests).
    allowMethods: ["OPTIONS", "GET", "POST", "PUT", "DELETE"],  // HTTP methods that you allow.
    allowHeaders: ["Content-Type", "X-Amz-Date", "Authorization", "X-Api-Key"],  // HTTP headers that can be used in a request.
    exposeHeaders: ["Content-Type"],  // Which response headers can be exposed as part of the response.
    maxAge: 300,  // Maximum caching time of preflight request results.
};

// Create a route for the OPTIONS method to enable CORS
const optionsRoute = new aws.apigatewayv2.Route("optionsRoute", {
    apiId: httpApi.id,
    routeKey: "OPTIONS /{proxy+}",  // A catch-all to attach CORS headers for any path in the API.
    target: "integrations/" + /* Integration ID for the Lambda or other target */,
});

// Define the response for the OPTIONS method
const optionsIntegration = new aws.apigatewayv2.Integration("optionsIntegration", {
    apiId: httpApi.id,
    integrationType: "MOCK",  // We use a mock integration since the response is static and does not require a backend service.
    integrationMethod: "OPTIONS",
    payloadFormatVersion: "2.0",
    templateSelectionExpression: "$request.method",
    requestTemplates: {
        "OPTIONS": JSON.stringify({
            statusCode: 200,
            headers: {
                "Access-Control-Allow-Origin": corsConfiguration.allowOrigins.join(","),
                "Access-Control-Allow-Methods": corsConfiguration.allowMethods.join(","),
                "Access-Control-Allow-Headers": corsConfiguration.allowHeaders.join(","),
                "Access-Control-Expose-Headers": corsConfiguration.exposeHeaders.join(","),
                "Access-Control-Max-Age": corsConfiguration.maxAge.toString(),
            },
        }),
    },
});

// Deploy the API Gateway
const deployment = new aws.apigatewayv2.Deployment("apiDeployment", {
    apiId: httpApi.id,
    // Ensure that changes to the API will create a new deployment
    triggers: {
        redeployment: JSON.stringify({
            routes: optionsRoute.id,
        }),
    },
});

// Stage represents an environment and a base URL for your API
const stage = new aws.apigatewayv2.Stage("apiStage", {
    apiId: httpApi.id,
    name: "dev",  // You can have different stages like dev, prod etc.
    deploymentId: deployment.id,
    autoDeploy: true,
});

// Export the stage URL so you know where to make requests to
export const httpApiUrl = stage.invokeUrl;
```

The program above is a complete setup of an AWS API Gateway to apply CORS rules via an `OPTIONS` route. Here's what it does, step by step:

1. We import the AWS module from Pulumi's AWS SDK.
2. We create an instance of `aws.apigatewayv2.Api`, representing the HTTP API.
3. `corsConfiguration` sets the rules for CORS, including allowed origins, HTTP methods, headers, and caching duration.
4. An `OPTIONS` route is created to handle preflight requests. This is the route that browsers send to determine whether the actual request is safe to send.
5. We create an instance of `aws.apigatewayv2.Integration`, which defines the preflight response. Since this is CORS, a "MOCK" type integration is used, meaning no backend is needed — the response is defined directly in the settings.
6. We create a deployment for our API which ensures that any changes are applied. The deployment references the options route via a `triggers` property to redeploy when changes occur.
7. The `stage` is a specific environment (like 'dev' or 'prod') for the API that is being deployed.
8. Finally, we expose the URL of the API using a Pulumi `export` so that it can be easily accessed from outside the Pulumi program.

Replace `/* Integration ID for the Lambda or other target */` with the actual integration ID pointing to your backend service such as a Lambda function.

This setup assumes you have a specific domain (`https://example.com`) that will be consuming your API and you are allowing typical HTTP methods along with specific headers for the requests.

You will need to replace placeholders and values specific to your environment (e.g., allowed origins, methods, headers) as needed.

After deploying this using Pulumi, you should be able to send requests from the specified origins to your HTTP API while respecting the CORS policy you've set up.