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 2.0 API definition. For details on how to configure an OpenAPI 3.0 API definition, see Editing an OpenAPI 3.0 API definition.
About this task
- When CORS is enabled, the API Gateway runs the
corspreflow 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:
corspreflow policy configures the appropriate response headers.
- The response headers are set.
- When a preflight request is received, the
request.attributes.isCORSPreflightflag is set to
- For all preflight requests, the
client-identificationpreflow 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 that corresponds to the design form in the user interface by clicking the Source icon . To return to the design form, click the Form icon .
To enable CORS support for an API, complete the following steps:
- Open the required API for editing, as described in Editing an OpenAPI 2.0 API definition.
Select the Gateway tab, expand Gateway and portal
settings, then click CORS. The CORS page opens.
- Select Enabled.
- 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:
- Alongside Policy, click Add.
- To include the header
Access-Control-Allow-Credentials: truein a response. select Allow Credentials. The
Request.credentials) is set to
- To append one or more of the following values to the
Access-Control-Expose-Headersresponse 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-Headersfrom the backend response.
- Custom - A custom string.
- Click Create.
- Alongside Allowed Origins click Add.
- 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 entry on the CORS page. You can then modify individual origin URLs, add further origins, and change the Allow Credentials setting.
- 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.
- Click Save to save your changes.
To implement your own CORS solution using custom OPTIONS operations,
complete the following steps:
Add the following headers to your HTTP responses:
Where <portalhostname> is your Developer Portal host name.
Access-Control-Allow-Origin: https://<portalhostname> Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
- Optional: You can proxy your API through API Connect as an enforced invoke API so that CORS is handled automatically.
- 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
OPTIONSmethod. Therefore, if you require these requests to be handled by the API Connect gateway then you must enable the
OPTIONSmethod for all APIs that will handle preflight requests; see Defining Paths for a REST API.
OPTIONSrequests 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.
- Add the following headers to your HTTP responses: