Enabling CORS support for an API

You can enable cross-origin resource sharing (CORS) support for your API. CORS allows embedded scripts in a web page to call the API across domain boundaries.

Before you begin

This task relates to configuring an OpenAPI 3.0 API definition. For details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API definition.

About this task

Note:

CORS support is available only on the DataPower® API Gateway.
When CORS is enabled, the API Gateway runs the cors preflow policy to handle all CORS requests that are made to the API.
When CORS is enabled and a preflight request is received, only the following API actions are performed:
- The cors preflow policy configures the appropriate response headers.
- The response headers are set.
When a preflight request is received, the request.attributes.isCORSPreflight flag is set to true.
For all preflight requests, the security and client-identification preflow policies are always skipped, whether CORS is enabled or not enabled.

You can complete this task either by using the API Designer UI application, or by using the browser-based API Manager UI.

At any time, you can switch directly to the underlying OpenAPI YAML source by clicking the Source icon OpenAPI Source icon . To return to the design form, click the Form icon Form icon .

Procedure

To enable CORS support for an API, complete the following steps:

Open the API for editing, as described in Editing an OpenAPI 3.0 API definition.
Select the Gateway tab, expand Gateway and portal settings, then click CORS.
The CORS page opens.
Select Enable CORS.
Optional: Configure a CORS policy.
Should you create a CORS policy? Review the following considerations:
- A CORS policy is an optional part of an API definition. If an API definition has no CORS policy but CORS is enabled, then CORS requests will be accepted from all Origins.
  If you want to accept CORS requests from all Origins, then enable CORS but do not add a CORS policy to the API definition.
- If you create a CORS policy, then CORS requests will only be accepted from Origins that are explicitly listed in the CORS rules contained in the CORS policy. CORS requests from any other Origins will be rejected.
  If you want to accept CORS requests from only a limited number of Origins (and might also want to configure the Access-Control-Allow-Credentials and Access-Control-Expose-Headers response headers), then you should enable CORS and create a CORS policy. Only those Origins explicitly listed in the allow-origin field of the CORS rules in the CORS policy will be accepted; CORS requests from any Origins not listed will be rejected.
- To configure a new CORS policy, complete the following steps:
  1. Alongside CORS Policy, click Add.
  2. To include the header Access-Control-Allow-Credentials: true in a response. select Allow Credentials. The Access-Control-Allow-Credentials response header tells browsers whether to expose the response to frontend JavaScript code when the request's credentials mode (Request.credentials) is set to include.
  3. To append one or more of the following values to the Access-Control-Expose-Headers response header, select Expose headers, and select from the following options:
    - Predefined - The predefined value of the Gateway. This option is selected by default.
    - Backend - The value of Access-Control-Expose-Headers from the backend response.
    - Custom - A custom string.
  4. Click Create.
  5. Alongside Allowed Origins click Add.
  6. Enter the origin URL, then click Create. This setting indicates that the response can be shared with requesting code from the specified origin.
- To modify an existing CORS policy, click its Allowed Origins entry on the CORS page. You can then modify individual origin URLs, add further origins, and change the Allow Credentials setting.
Example
The following example has three rules:
- Accept an Origin header of https://example.com, and return Access-Control-Allow-Credentials: true in the CORS response.
- Accept an Origin header of http://domain.com. No Access-Control-Allow-Credentials header will be returned in the response.
- Accept any of the following Origin headers:
  
  http://example2.com
  
  http://example3.com
  
  http://example4.com
  
  No Access-Control-Allow-Credentials header will be returned in the response.
```
  cors:
    enabled: true
    policy:
      -
        allow-origin:
          - 'https://example.com'
        allow-credentials: true
      -
        allow-origin:
          - 'http://domain.com'
      -
        allow-origin:
          - 'http://example2.com'
          - 'http://example3.com'
          - 'http://example4.com'
```
Click Save to save your changes.
Optional: To implement your own CORS solution using custom OPTIONS operations, complete the following steps:
1. Add the following headers to your HTTP responses:
```
Access-Control-Allow-Origin: https://<portalhostname>
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept 
```
  Where <portalhostname> is your Developer Portal host name.
2. Optional: You can proxy your API through API Connect as an enforced invoke API so that CORS is handled automatically.
Important:
- If you implement your own CORS solution, you must disable the CORS option described in step 3
- CORS preflight requests are sent by using the HTTP OPTIONS method. Therefore, if you require these requests to be handled by the API Connect gateway then you must enable the OPTIONS method for all APIs that will handle preflight requests; see Defining Paths for a REST API.
- OPTIONS requests are counted as API calls against any configured rate limit. Note that you can apply rate limits to individual operations; see Defining rate limits for an API operation.