Configuring CORS for APIs

Overview

For security purposes, the browser restricts the cross-domain requests from being initiated from a page script. In this case, the page can access only the resources from the current domain. CORS allows the browser to send XMLHttpRequest requests to the server in a different domain.

Figure 1 Process flow of the CORS mechanism

CORS requests are classified into two types: simple requests and not-so-simple requests.

A request that meets both of the following conditions is a simple request:
- The request method is HEAD, GET, or POST.
- The HTTP header can contain only the following fields: Accept, Accept-Language, Content-Language, Last-Event-ID and Content-Type (only three values are allowed: application/x-www-form-urlencoded, multipart/form-data, and text/plain).
In the header of a simple request, browsers automatically add the Origin field to specify the origin (including the protocol, domain, and port) of the request. After receiving such a request, the target server determines based on the origin whether the request is safe and can be accepted. If the server sends a response containing the Access-Control-Allow-Origin field, the server accepts the request.
Any request that does not meet the preceding two conditions is a not-so-simple request.
Before sending a not-so-simple request, browsers send an HTTP preflight request to the target server to determine whether the origin the web page is loaded from is in the allowed origin list, and which HTTP request methods and header fields can be used. If the preflight is successful, browsers send simple requests to the server.

By default, ROMA Connect does not support CORS. To enable ROMA Connect to support CORS, enable CORS when creating an API. If the CORS request is a not-so-simple request, you also need to create an API that uses the OPTIONS method as the preflight request.

Simple Requests

Scenario 1: If CORS is enabled and the response from the backend does not contain a CORS header, ROMA Connect can handle requests from any domain, and returns the Access-Control-Allow-Origin CORS header. The following messages are used as examples:
1. Request sent by a browser and containing the Origin header field:
```
GET /simple HTTP/1.1
Host: www.test.com
Orgin: http://www.cors.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Accept: application/json
Date: Tue, 15 Jan 2019 01:25:52 GMT
```
  Origin: This field specifies the origin (http://www.cors.com in this example) of the request. It is mandatory. ROMA Connect and the backend service determine based on the origin whether the request is safe and can be accepted.
2. Response sent by the backend:
```
HTTP/1.1 200 OK
Date: Tue, 15 Jan 2019 01:25:52 GMT
Content-Type: application/json
Content-Length: 16
Server: roma

{"status":"200"}
```
3. Response sent by ROMA Connect:
```
HTTP/1.1 200 OK
Date: Tue, 15 Jan 2019 01:25:52 GMT
Content-Type: application/json
Content-Length: 16
Server: roma
X-Request-Id: 454d689fa69847610b3ca486458fb08b
Access-Control-Allow-Origin: *

{"status":"200"}
```
  Access-Control-Allow-Origin: This field is mandatory. The asterisk (*) indicates that ROMA Connect accepts requests from any domain.
Scenario 2: If CORS is enabled and the response from the backend contains a CORS header, the header will overwrite that added by ROMA Connect. The following messages are used as examples:
1. Request sent by a browser and containing the Origin header field:
```
GET /simple HTTP/1.1
Host: www.test.com
Orgin: http://www.cors.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Accept: application/json
Date: Tue, 15 Jan 2019 01:25:52 GMT
```
  Origin: This field specifies the origin (http://www.cors.com in this example) of the request. It is mandatory. ROMA Connect and the backend service determine based on the origin whether the request is safe and can be accepted.
2. Response sent by the backend:
```
HTTP/1.1 200 OK
Date: Tue, 15 Jan 2019 01:25:52 GMT
Content-Type: application/json
Content-Length: 16
Server: roma
Access-Control-Allow-Origin: http://www.cors.com

{"status":"200"}
```
  Access-Control-Allow-Origin: Indicates that the backend service accepts requests sent from http://www.cors.com.
3. Response sent by ROMA Connect:
```
HTTP/1.1 200 OK
Date: Tue, 15 Jan 2019 01:25:52 GMT
Content-Type: application/json
Content-Length: 16
Server: roma
X-Request-Id: 454d689fa69847610b3ca486458fb08b
Access-Control-Allow-Origin: http://www.cors.com

{"status":"200"}
```
  The CORS header in the backend response overwrites that in ROMA Connect's response.

Not-So-Simple Requests

For a non-simple request, you also need to create an API that uses the OPTIONS method. The request parameters of an API accessed using the OPTIONS method must be set as follows:

API Group: Same as the group to which the API with CORS enabled belongs.
Security Authentication: No authentication is required for requests received by the new API no matter which security authentication mode has been selected.
Protocol: Same as the protocol used by the API with CORS enabled.
Request Path: Same as or matching the request path used by the API with CORS enabled.
Method: Set to OPTIONS.
CORS: Enabled.

The following are example requests and responses sent to or from a mock backend.

Request sent from a browser to an API that is accessed using the OPTIONS method:
```
OPTIONS /HTTP/1.1
User-Agent: curl/7.29.0
Host: localhost
Accept: */*
Origin: http://www.cors.com
Access-Control-Request-Method: PUT 
Access-Control-Request-Headers: X-Sdk-Date
```
- Origin: This field is mandatory and used to specify the origin from which the request has been sent.
- Access-Control-Request-Method: This field is mandatory and used to specify the HTTP methods to be used by the subsequent simple requests.
- Access-Control-Request-Headers: This field is mandatory and used to specify the additional header fields in the subsequent simple requests.
Response sent by the backend:
None

Response sent by ROMA Connect:

HTTP/1.1 200 OK
Date: Tue, 15 Jan 2019 02:38:48 GMT
Content-Type: application/json
Content-Length: 1036
Server: roma
X-Request-Id: c9b8926888c356d6a9581c5c10bb4d11
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: X-Stage,X-Sdk-Date,X-Sdk-Nonce,X-Proxy-Signed-Headers,X-Sdk-Content-Sha256,X-Forwarded-For,Authorization,Content-Type,Accept,Accept-Ranges,Cache-Control,Range
Access-Control-Expose-Headers: X-Request-Id,X-Apig-Latency,X-Apig-Upstream-Latency,X-Apig-RateLimit-Api,X-Apig-RateLimit-User,X-Apig-RateLimit-App,X-Apig-RateLimit-Ip,X-Apig-RateLimit-Api-Allenv
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH
Access-Control-Max-Age: 172800

Access-Control-Allow-Origin: This field is mandatory. The asterisk (*) indicates that ROMA Connect accepts requests from any domain.
Access-Control-Allow-Headers: This field is required if it is contained in the request. It specifies the header information field supported by ROMA Connect.
Access-Control-Allow-Methods: This field is mandatory and used to specify the HTTP request method supported by ROMA Connect. .
Access-Control-Max-Age: This field is mandatory and used to specify the period (in seconds) during which the preflight result remains valid. No more preflight requests are needed within the period.

Request sent by a browser and containing the Origin header field:

PUT /simple HTTP/1.1
Host: www.test.com
Orgin: http://www.cors.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Accept: application/json
Date: Tue, 15 Jan 2019 01:25:52 GMT

Response sent by the backend:

HTTP/1.1 200 OK
Date: Tue, 15 Jan 2019 01:25:52 GMT
Content-Type: application/json
Content-Length: 16
Server: roma

{"status":"200"}

Response sent by ROMA Connect:

HTTP/1.1 200 OK
Date: Tue, 15 Jan 2019 01:25:52 GMT
Content-Type: application/json
Content-Length: 16
Server: roma
X-Request-Id: 454d689fa69847610b3ca486458fb08b
Access-Control-Allow-Origin: *

{"status":"200"}

Parent topic: Calling an API

Previous topic: Calling an Open API

Next topic: Appendix: API Error Codes