Cross-Origin Resource Sharing (CORS)

Last Updated：2020-09-07

1.1 Two Verification Mode

The CORS verification mechanism has two modes: Simple request and prior request.

When the request simultaneously meets the following three conditions, the CORS verification mechanism uses the simple mode for processing.

1.The request method is one of the following:

GET
HEAD
POST

2.The value of the Content-Type request header in the request headers is one of the following:
application/x-www-form-urlencoded
multipart/form-data
text/plain

3.The Fetch specification defines an assembly of CORS security headers (user-defined headers in the cross-origin requests belong to the assembly of security headers), and the assembly is:
Accept
Accept-Language
Content-Language
Content-Type (pay attention to additional limitations)
DPR
Downlink
Save-Data
Viewport-Width
Width

Or the CORS verification mechanism uses the prior request mode for processing.

1.2 Simple Request Mode

In the simple request mode, the browser directly sends a cross-origin request, and carries the header of Origin in the request header. This indicates that this is a cross-origin request. After receiving a request, the server side returns the verification results through the Access-Control-Allow-Origin and Access-Control-Allow-Methods response headers based on its own cross-origin rules.

Simple Request Mode

The response carries the cross-origin header Access-Control-Allow-Origin. The simplest access control may be completed by Origin and Access-Control-Allow-Origin. In the example, the Access-Control-Allow-Origin:* returned by the server side indicates that the resource may be accessed by any external domain. If the server side only allows the access from http://cloud.agilecloud.com, the contents of the header field are as follows:

Access-Control-Allow-Origin: http://cloud.agilecloud.com

Now, except for http://cloud.agilecloud.com, no other exterior domains can access the resource.

1.3 Prior Request Mode

When finding that the request sent by the page is not a simple request, the browser doesn't execute the corresponding request, but triggers the prior request mode. The prior request mode first sends Preflighted requests (prior verification request). The Preflighted request is one OPTIONS request and used to query whether the server to be accessed by cross-origin allows the page under the current domain name to send a cross-origin request. A real HTTP request may be sent only after the cross-origin authorization is obtained from the server.

The OPTIONS request header can include the following headers: Origin, Access-Control-Request-Method, Access-Control-Request-Headers. After the server receives the OPTIONS request, the Access-Control-Allow-Origin, Access-Control-Allow-Method, Access-Control-Allow-Headers, Access-Control-Max-Age headers are set to communicate with the browser to judge whether the request is allowed. The browser can send a real cross-origin request only if the Preflighted requests is verified.

Prior Request Mode

The cross-origin header Access-Control-Request-Method in the requests tells the server that the actual request is to use the GET method. The cross-origin header Access-Control-Request-Headers in the requests tells the server that the actual request is to carry two user-defined request header fields: x-ca-nonce and content type. The server decides whether the actual request is allowed based on this.

The cross-origin header Access-Control-Allow-Methods in the responses indicates that the server allows the client-side to use the GET method to initiate a request. The values form a list separated by commas.

The cross-origin header Access-Control-Allow-Headers in the responses indicates that the server allows the request to carry fields of x-ca-nonce and content-type. Being the same as Access-Control-Allow-Methods, the values of Access-Control-Allow-Headers form a list separated by commas.

The cross-origin header Access-Control-Max-Age in the responses indicates that the valid time of the response is 86,400 seconds, namely, 24 hours. Within the valid time, the browser may not initiate a preview request for the same request again. Please note that the browser itself maintains a maximum valid time. The value of the header field doesn't become valid if exceeding the maximum valid time.

2.Realization of CORS in the API Gateway

2.1 Realization of Simple Request Mode

The API Gateway allows all APIs to make cross-origin access by default. So in case of no special return in the responses of API back-end services of users, the API Gateway returns related headers allowing the cross-origin access by all fields.

The following is an example:

API request of client-side

GET/simple HTTP/1.1 
Host: bdcloudapi.com 
Orgin: cloud.agilecloud.com 
content-type: application/x-www-form-urlencoded; charset=utf-8 
accept: application/json; charset=utf-8 
date: Tue, 05 Nov 2019 11:04:10 GMT

Back-end service response

HTTP/1.1 200 OK 
Date: Tue, 05 Nov 2019 11:04:10 GMT 
Content-Type: application/json; charset=UTF-8 
Content-Length: 12
{"200","OK"}

API Gateway response

HTTP/1.1 200 OK 
Date: Tue, 05 Nov 2019 11:04:10 GMT 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH 
X-Bce-Request-Id: 63c4a3a9-8636-4510-a54f-595fa74069e4
Content-Type: application/json; charset=UTF-8 
Content-Length: 12
{"200","OK"}

As can be seen from the three messages above, the API Gateway makes certain modifications to the back-end service responses of users, and adds two cross-origin headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,HEAD,OPTIONS,PATCH

The cross-origin header means that the API allows the request access by all fields. The request methods allowing the cross origin include the seven kinds listed in the request headers.

To customize the cross-origin headers of responses for simple requests, the users may only add the cross-origin header Access-Control-Allow-Origin in the back-end service responses. The headers in the back-end service responses override the headers added by the API Gateway itself by default. The following is an example. The API in the example only allows the access of the domain cloud.agilecloud.com:

API request of client-side

GET/simple HTTP/1.1 
Host: bdcloudapi.com 
Orgin: cloud.agilecloud.com 
content-type: application/x-www-form-urlencoded; charset=utf-8 
accept: application/json; charset=utf-8 
date: Tue, 05 Nov 2019 11:04:10 GMT

Back-end service response

HTTP/1.1 200 OK 
Access-Control-Allow-Origin: cloud.agilecloud.com
Access-Control-Allow-Methods: GET 
Date: Tue, 05 Nov 2019 11:04:10 GMT 
Content-Type: application/json; charset=UTF-8 
Content-Length: 12
{"200","OK"}

API Gateway response

HTTP/1.1 200 OK 
Access-Control-Allow-Origin: cloud.agilecloud.com
Access-Control-Allow-Methods: GET 
X-Bce-Request-Id: 63c4a3a9-8636-4510-a54f-595fa74069e4
Date: Tue, 05 Nov 2019 11:04:10 GMT 
Content-Type: application/json; charset=UTF-8 
Content-Length: 12
{"200","OK"}

2.2 Realization of Prior Request Mode

The browser uses the OPTIONS method to send a prior request to acquire the information of cross-origin request required by the server.

We can configure an API in the API Gateway, set the API method as OPTIONS, and match all subpaths. This can allow the prior request to be routed to the API, and return the responses allowing the cross-origin request.

Refer to the API related documents for the creation process of API. The configuration points to be noted are as follows.

1.Set the security authentication method as "No Authentication".