Using the CORS Policy
Learn how to manage cross-origin requests for REST APIs using the CORS (Cross-Origin Resource Sharing) Policy.
Note: This topic describes features only available in API Gateway version 7.0 or greater.
Supported Platforms: 7.1, 7.2, 8.0
Table of Contents
CORS (Cross-Origin Resource Sharing) enables users to access resources from within the browser serving a web page, and defines a way in which the browser and the server can interact to determine whether or not to allow the cross-origin request. This technique is commonly used on the web to load (that is, share) resources such as CSS style sheets, images, scripts, and other resources across sites. Abuse of this functionality can be a security risk; A CORS policy can be configured to limit or refuse cross-origin resource sharing.
Many HTTP (REST) APIs require support for CORS. Policy Manager provides a CORS Policy that dictates how cross-origin requests or CORS headers should be processed.
A CORS policy applies only to REST APIs, or service endpoints implementing the HTTP binding. Accordingly, the CORS assertion is allowed to have the following Policy Subjects as defined in the WS-PolicyAttachment specification:
- Endpoint Policy Subject
- Binding Policy Subject
The WS-PolicyAttachment specification defines a set of WSDL/1.1 policy attachment points for each of the above Policy Subjects. A CORS policy assertion can be attached to the following physical WSDL policy attachment points:
A CORS policy does not dictate behavior that is required by a consumer in order to exchange messages between a consumer and a Provider. Instead it dictates behavior that only the provider must follow. Therefore it is recommended that CORS policies be classified as “public” by including the gmp:Visibility attribute in the enclosing wsp:Policy element with a value of “public.”
The following is an example of a CORS policy attached to WSDL components:
Lines 02 through 06 contain a policy named "CORS" that holds a CORS assertion.
CORS Policy Assertion
The CORS assertion specifies how responses to CORS requests, simple or preflight, will be made. Each CORS response header, with the exception of Access-Control-Request-Method, is represented with a sub-assertion to identify how it should be returned. The Access-Control-Request-Method response is determined by the API definition.
The syntax of the CORS policy assertion is illustrated and explained below.
- CORS assertion element.
- This element defines additional requirements for the CORS policy.
- This mandatory element is an assertion that specifies the set of origins that are allowed. If no child elements (allowed origins) are defined, the Access-Control-Allow-Origin response header is not displayed.
- This optional string element identifies an allowed origin. The string can either be a host name by itself or a protocol schema and host such as http://acme.com. If no scheme is specified, all schemes for that host are allowed.
- This optional element is an assertion that when present indicates that the Access-Control-Allow-Credentials response header will be “true.” When absent it will be “false.”
- This optional element is an assertion that specifies what headers should be returned in the Access-Control-Expose-Headers response header. If it is not present, no headers will be returned.
- cors:CORS/wsp:Policy/cors:ExposeHeader/cors: Header
- This optional string element identifies an exposed header.
- This optional element is an assertion that specifies what headers should be returned in the Access-Control-Allow-Headers response header. If it is not present, no headers will be returned.
- This optional string element identifies an allowed header.
- This optional element defines the time period in seconds. When the max age is set, a CORS request will not need to be preflighted, if it has already been preflighted, and falls within the max age duration.
- cors:CORS/wsp:Policy/cors:MaxAge /@duration
- This mandatory integer attribute holds the value that will be returned in the Access-Control-Max-Age response header.
An example of a CORS policy is given below.
The acme.com origin is permitted only on line 05. Credentials are allowed on line 07. The X-PINGOTHER header is allowed on line 09. A max duration of 3600000, or one hour, is stated on line 11. The CORS response headers that will be returned to a preflight request with an Origin of http://acme.com are shown below.
Note: Allowed Methods are outside the scope of the CORS Policy. Policy Manager returns methods based on how the service is defined. For example, if you defined a REST service in Policy Manager and defined operating using HTTP methods, Policy Manager would return the HTTP methods you defined for the service.
Note there is no Access-Control-Expose-Headers response header as there was no assertion present. Since the policy did not specify a protocol scheme for the allowed origin, a request with an Origin header of https://acme.com would also have been permitted.
The policy includes the following configuration options:
|Max Age||This optional element defines the time period in seconds. When the max age is set, a CORS request will not need to be preflighted, if it has already been preflighted, and falls within the max age duration.|
|Allow Credentials||Enable sending credentials (that is, cookies and HTTP Authentication data) with requests.|
List of origin domains that are permitted to make a request against the service via CORS. The origin domain is the domain from which the request originates.
If no child elements (allowed origins) are defined, the Access-Control-Allow-Origin response header is not displayed.
Each header can include one domain.
|Allow Headers||Request headers that the origin domain might specify on the CORS request.|
|Expose Headers||Response headers that might be sent in the response to the CORS request and exposed by the browser to the request issuer.|
Let's take a quick walkthrough of the CORS Policy configuration process to get you started.
Step 1: Add Policy
In Policy Manager, to create a CORS Policy instance, go to Policies > Operational Policies and choose Add Policy.
Step 2: Modify Policy
When you click Modify to make changes to the CORS Policy on the Policy Details page, the initial policy looks like this:
Configure the CORS Options based on your requirements.
Step 3: Attach Policy
After you've saved your policy, you can attach it to a web service at the Service level.
Step 4: Test Policy and View Monitoring Data
After you've attached the CORS Policy to a service, send a request to your service and view the results in your client. You can also go to the Services > Monitoring section to view the results for Logs (View Usage Record Details), Real Time Charts, and Historical Charts. For more information on using the monitoring functions, refer to the Policy Manager Online Help, available via the Help button. Notes:
- If CORS is enabled for the service and there is a CORS policy assertion that matches the preflight request, the service responds with a status code 200 (OK), and includes the required Access-Control headers in the response.
- If CORS is not enabled for the service, the request is not preflighted.
- If the request does not contain the required CORS headers, the request is not preflighted and continues to run normally, and the browser behaves accordingly.
- If the Origin header is present, this indicates that the request is a CORS request. The service will then check the matching CORS policy assertion configuration for a match. If found, the Access-Control headers are added to the response and sent back to the client. If not found, the CORS Access-Control headers are not returned.
For more information on the configuration and test cycle, refer to CORS Policy Usage Scenarios.