asp.net Web API 2 support for CORS

Cross-domain resource sharing (CORS) is a World Wide Web Consortium (commonly considered part of the HTML5) that allows JavaScript to overcome the same domain policy security restrictions imposed by browsers. The same domain strategy is that JavaScript can only make AJAX callbacks to the same domain that contains the Web page (where "domain" is a combination of host names, protocols, and port numbers). For example, JavaScript on a Web page in http://foo.com cannot have http://bar.com (or http://www.foo.com, https://foo.com, or http://foo.com:999, etc.) AJAX invocation.

CORS allows the server to indicate which domains are allowed to invoke them, thereby relaxing this restriction. CORS is enforced by the browser and must be implemented on the server, while the latest version of ASP.net Web API 2 fully supports CORS. With Web API 2, you can configure policies to allow JavaScript clients from different domains to access your APIs.

CORS Basic Information

Because the Web API is implemented exactly according to this specification, it will be helpful to learn more about CORS itself in order to use the new CORS functionality in the Web API. These details may now appear to be theoretical, but will be useful for future understanding of the settings available in the Web API: When you debug CORS, they help you solve the problem more quickly.

The general mechanism of CORS is that when JavaScript attempts to make Cross-domain AJAX calls, the browser "asks" whether the server is allowed to make such calls by sending headers (such as "Origin") in the HTTP request. The server indicates the allowed operation by returning an HTTP header (such as "Access-control-allow-origin") in the response. This permission check will be made for each different URL called by the client, which means that different URLs can have different permissions.

In addition to domains, CORS can also have the server indicate the HTTP methods that are allowed, the HTTP request headers that the client can send, the HTTP response headers that the client can read, and whether to allow the browser to automatically send or receive credentials (cookies or authorization headers). Other request and response headers indicate which features are allowed to be used. Figure 1 summarizes these headers (note that some of the features do not have headers sent in the response, only responses).

Figure 1 CORS HTTP headers

Browsers can request these permissions from the server in two different ways: a simple CORS request and a pre-check CORS request.

Simple CORS request. The following is an example of a simple CORS request:

POST http://localhost/WebApiCorsServer/Resources/HTTP/1.1

Host:localhost

Accept: */*

origin:http://localhost:55912

content-type:application/x-www-form-urlencoded; Charset=utf-8

Value1=foo&value2=5

The response is as follows:

http/1.1 OK

Content-type:application/json; Charset=utf-8

access-control-allow-origin:http://localhost:55912

Content-length:27

{"Value1": "foo", "Value2": 5}

The request is a Cross-domain request from http://localhost:55912 to http://localhost, and the browser adds a "Origin" HTTP header to the request to indicate the calling domain of the server. The server responds with the "Access-control-allow-origin" response header, indicating that the domain is allowed to be used. The browser enforces the policy for the server, and JavaScript receives its normal successful callback.

The server either can respond with an exact field value from the request, or you can use a value that indicates "*" that allows any domain to be used. If the calling domain is not yet allowed by the server, the "Access-control-allow-origin" header is missing and causes an error callback to invoke JavaScript.

Note that when a simple CORS request is made, the server is still invoked. It may seem strange if you don't understand CORS, but this behavior is tantamount to the case where the browser has constructed <form> elements and made a normal POST request. CORS does not block calls to the server, but it blocks calls to JavaScript to receive results. If you want to block callers from calling the server, you need to implement some kind of authorization in server code (you might want to use [Authorize] authorization filter properties).

The preceding example is called a simple CORS request because the type of the AJAX call from the client is either get or POST; Content-type is application/x-www-form-urlencoded, multipart/ One of the Form-data or Text/plain, and no other request headers are sent. If the AJAX call is another HTTP method, Content-type is some other value, or the client wants to send another request header, the request is treated as a pre-check request. The mechanism of the pre-inspection request is slightly different.

Pre-check CORS request. If the AJAX call is not a simple request, it requires a CORS request, which is simply an additional HTTP request sent to the server to get permission. This prefetch request is automatically emitted by the browser and uses the options HTTP method. If the server successfully calls for a prefetch request and grants permissions, the browser executes the actual AJAX call that JavaScript is trying to perform.

If you are concerned about performance issues (and when performance issues occur), the browser can cache the results of this prefetch request by including the Access-control-max-age header in the pre-test response. The value contains the number of seconds that the permission can be cached.