CORS support for APIs in gateway

[RakhithaRR]

CORS Support

CORS support should be available in the gateway to facilitate browser based clients to access the APIs deployed in the gateway. To cater this requirement, we have two options on our hands.

Option 1 - CORS Policy through policy engine

This will be a policy that can be applied per API. A sample policy definition would look like follows.

name: CORS
version: v1.0.0
description: |
  Cross-Origin Resource Sharing (CORS) policy that handles preflight requests and adds
  appropriate CORS headers to responses. Enables controlled access to resources from different
  origins by configuring allowed origins, methods, headers, and credentials.

parameters:
  type: object
  properties:
    allowedOrigins:
      type: array
      description:
        List of origins allowed to access the resource. Use "*" to allow
        all origins, or specify exact origins (e.g., "https://example.com"). At least
        one origin must be specified.
      items:
        type: string
        minLength: 1
        maxLength: 2048
      minItems: 1
    allowedMethods:
      type: array
      description:
        HTTP methods allowed for cross-origin requests. Common methods
        include GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD.
      items:
        type: string
        enum:
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
          - OPTIONS
          - HEAD
      minItems: 1
      default:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS
    allowedHeaders:
      type: array
      description:
        Request headers that can be used in the actual request. Use "*"
        to allow all headers, or specify exact header names (e.g., "Content-Type",
        "Authorization").
      items:
        type: string
        minLength: 1
        maxLength: 256
      default:
        - "*"
    exposedHeaders:
      type: array
      description:
        Response headers that browsers are allowed to access. Only these
        headers will be exposed to the client-side JavaScript code.
      items:
        type: string
        minLength: 1
        maxLength: 256
      default: []
    allowCredentials:
      type: boolean
      description: Indicates whether the response can be shared when credentials
        (cookies, authorization headers, TLS certificates) are included. When true,
        allowedOrigins cannot contain "*".
      default: false
    maxAge:
      type: integer
      description: Maximum time in seconds that preflight response can be cached
        by the browser. Helps reduce the number of preflight requests.
      minimum: 0
      maximum: 86400
      default: 3600
    forward_not_matching_preflight:
      type: boolean
      description: If true, forwards preflight requests that do not match the CORS
        policy to the upstream service instead of responding with CORS headers.
      default: false

  required:
    - allowedOrigins

systemParameters:
  type: object
  properties: {}

Option 2 - Envoy CORS Filter

We will hand over the CORS handling to envoy's CORS filter (https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/cors_filter#config-http-filters-cors).

This filter will be attached to each route. This supports all the parameters defined in the option 1 as well as some additional parameters. More information can be found in https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/cors/v3/cors.proto.html#extensions-filters-http-cors-v3-corspolicy

The actual configs will have to be provided through the configuration yaml files. If this is given as a policy, there's nothing to be implemented inside the policy logic.

Concerns

Both these options require an actual route to function. i.e. the gateway should have an OPTIONS route to serve the preflight requests for each of the actual routes. The policy engine creates the policy chain per route and the envoy filter is also attached per route. If the route does not exist, neither of those options would be engaged.

As a solution, we can explore the following

• Create an OPTIONS route for every route in the gateway.
• Instead of an exact match for the method in the route, we can do a regex based matching (^(GET|OPTIONS)$)
• Add a fallback route which catches all the non existent routes and then do the processing there

[renuka-fernando]

Key Design Requirements

1. CORS as a Regular Policy

CORS must be treated as a regular policy without special handling in the Gateway Controller. The Policy Engine is responsible for all CORS functionality.

Design Principle: CORS is not a special case - it is just another policy like any other (apiKey, jwt, rateLimit, etc.).

Implications:

• Gateway Controller does not have CORS-specific logic or configuration
• All CORS processing (preflight handling, header injection, validation) happens in the Policy Engine
• CORS policy follows the same lifecycle and configuration patterns as other policies

2. Automatic OPTIONS Route Generation

The Gateway Controller must automatically generate OPTIONS routes for all API paths (whether CORS is enabled or not) to handle CORS preflight requests properly.

3. Path-Level CORS Configuration Conflicts

CORS configuration must be consistent across all HTTP methods for a given path. However, users can technically define conflicting CORS configurations for different methods on the same path (similar to any other policy).

Constraint: The system allows this configuration, but it is invalid and produces undefined behavior.

Example - Invalid Configuration:

operations:
  - method: GET
    path: /foo
    policies:
      - name: cors
        params:
          allowHeaders: [Get-Header]  # CORS config A

  - method: PUT
    path: /foo
    policies:
      - name: cors
        params:
          allowHeaders: [Put-Header]  # CORS config B - CONFLICT!

Action Required: The CORS policy documentation must explicitly warn users that different CORS configurations for the same path (across different methods) is invalid and will result in undefined behavior.

4. Explicit OPTIONS Route Handling

When a user explicitly defines an OPTIONS method for a path, the CORS policy implementation must assume that CORS is handled by the backend and pass the request through without modification.

Example:

operations:
  - method: GET
    path: /bar
    policies:
      - name: cors  # Gateway should generate automatic OPTIONS /bar for preflight

  - method: OPTIONS
    path: /bar      # User explicitly defined - passes to backend, no CORS handling

Behavior: The presence of an explicit OPTIONS route takes precedence over automatic CORS preflight handling.

5. API Object in Policy Engine (Same as Application, Subscription in the future)

The Policy Engine requires knowledge of all routes defined for an API to properly handle CORS. The Gateway Controller must pass the complete API YAML specification to the Policy Engine.

Rationale: CORS headers in preflight responses must accurately reflect all allowed methods for a path, which requires visibility into all operations.

Example Configuration

Complete API with CORS Policies

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: RestApi
metadata:
  name: weather-api-v1.0
spec:
  displayName: Weather-API
  version: v1.0
  context: /weather/$version
  upstream:
    main:
      url: http://sample-backend:5000/api/v2

  # API-level CORS policy (If user defines here, it applies to all paths and skips operation-level CORS)
  policies:
    - name: cors
      version: v0.1.0
      params:
        allowOrigins:
          - http://example.com
          - http://another-example.com
        allowMethods:  # Defaults to all methods defined for each path
          - GET
          - POST
          - PUT
          - DELETE
        allowHeaders:
          - Content-Type
          - Authorization
        exposeHeaders:
          - X-Custom-Header
        allowCredentials: true
        maxAge: 3600

  operations:
    # INVALID: Operation-level CORS overrides for same path (undefined behavior)
    # This creates a conflict - path /foo has different CORS configs
    - method: GET
      path: /foo
      policies:
        - name: cors
          version: v0.1.0
          params:
            allowHeaders: [Get-Header]  # Override for GET

    - method: PUT
      path: /foo
      policies:
        - name: cors
          version: v0.1.0
          params:
            allowHeaders: [Put-Header]  # CONFLICT: Different config for same path!

    - method: GET
      path: /bar
      policies:
        - name: cors
          version: v0.1.0
          params:
            allowHeaders: [Get-Header]

    # Explicit OPTIONS route - CORS handled by backend
    - method: OPTIONS
      path: /bar
      # No CORS policy - request passes through to backend

[nuwand]

The CORS policy should be a regular policy (available on policy hub, applied through the policy engine). The Gateway should not add any routes automatically. If users require CORS they should define the required resources + method (OPTIONS) and handle CORS by attaching the policy.