aws-apigateway: introduce convenience method for adding CORS headers to authorizer responses

[garysassano]

Describe the feature

When using custom authorizers with API Gateway, CORS headers are not automatically added to 401 responses since these responses come directly from the authorizer before reaching any Lambda integration. This requires developers to manually add Gateway Responses with CORS headers for each API Gateway instance, leading to repetitive boilerplate code.

This proposal suggests adding a convenience method addAuthorizerCORSHeaders() to the RestApi class to streamline this common use case.

Use Case

When building web applications that use API Gateway with custom authorizers, browsers require proper CORS headers even for unauthorized (401) responses. Currently, developers need to manually add Gateway Responses like this for each API:

new apigateway.GatewayResponse(this, "UnauthorizedResponse", {
  restApi: api,
  type: apigateway.ResponseType.UNAUTHORIZED,
  responseHeaders: {
    "Access-Control-Allow-Origin": "'*'",
  }
});

This is repetitive and easy to forget, leading to CORS issues that are hard to debug.

Proposed Solution

Add a simple convenience method to RestApi:

class RestApi {
  /**
   * Adds CORS headers to 401 responses from authorizers.
   * This adds Access-Control-Allow-Origin: '*' to enable
   * proper error handling in browser applications.
   */
  public addAuthorizerCORSHeaders(): void {
    // Internally creates the necessary GatewayResponse resource
    // with Access-Control-Allow-Origin: '*' for 401 responses
  }
}

Usage would be as simple as:

const api = new apigateway.RestApi(this, "api", {
  // ... other options
});

api.addAuthorizerCORSHeaders();

For cases requiring custom CORS settings, developers can still use the GatewayResponse construct directly.

Other Information

This is a common issue that many developers face when working with API Gateway custom authorizers, as evidenced by:

• Stack Overflow questions like AWS API Gateway and Authorizer CORS error
• Medium articles like AWS Serverless how to fix CORS for custom lambda authorizer

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

2.178.2

Environment details (OS name and version, etc.)

Ubuntu 24.04.1

[pahud]

Sounds good. It addresses a common pain point with API Gateway custom authorizers and CORS and reduces boilerplate code. Please help us prioritize with 👍 and we welcome PRs.