Cross-Origin Resource Sharing

Cross-Origin Resource Sharing (CORS) is a W3C-recommended mechanism that enables restricted resources (such as stylesheets, images and fonts) on a web page to be requested securely from another domain outside the domain from which the resource originated.

All modern web browsers enforce a Same-Origin Policy, which limits scripts running in one domain from accessing resources that are hosted in another. For example, a script that is running at http://some-questionable-site.com can make AJAX (asynchronous JavaScript and XML) calls to the some-questionable-site.com domain and receive a response; while it can make requests to http://your-bank.com, reads are blocked and the requests fail. The Same-Origin Policy is a cornerstone of internet security and helps protect against a wide array of attacks that would otherwise be possible.

Unfortunately, this means that modern, trustworthy applications that are running in one domain cannot make AJAX requests to resources that are hosted in another domain. This presents a problem if, for example, you are developing an application that will run at http://my-internal-site.internal/mygreatapp and you are trying to make AJAX calls to the PI Web API, which is running at https://my-pisystem.internal/piwebapi.

The solution is to enable CORS in the PI Web API configuration and indicate the origins from which PI Web API accepts cross-domain requests. All modern browsers support CORS as a workaround for the same-origin policy.

Caution: Some CORS configuration settings accept a wildcard, which effectively disables that defense. The use of wildcards weakens the CORS mechanism and may leave your application vulnerable. We recommend not using wildcards unless otherwise required.

More information about CORS is available at W3C Recommendation on Cross-Origin Resource Sharing. Information about its use in ASP.NET Web API is available in an MSDN magazine article titled ASP.NET Web API - CORS Support in ASP.NET Web API 2.

The following CORS configuration items are available in PI Web API:

CorsHeaders

A comma-separated list of HTTP header keys that are allowed for cross-domain requests. The client browser enforces this restriction.

The default value of null, or an empty string, indicates that no HTTP headers can be sent with the request. The client browser suppresses any HTTP headers that you attempt to set manually.

The asterisk (*) character is a wildcard and means that the client browser is free to forward any HTTP headers with the request. The use of wildcards is not recommended. For more information, see the caution above.

If you are making requests that include content, for example creating or updating a resource in PI Web API, you can add the Content-Type header as an allowed header in the CorsHeaders property.

CorsMethods

A comma-separated list of HTTP methods (verbs) that are allowed for cross-domain requests. PI Web API inspects the provided HTTP method against the list of allowed values to make an authorization decision.

The default value, GET,OPTIONS, means that only HTTP calls that use one of those two HTTP methods will be accepted. This limits cross-domain requests to read access only, for enhanced security.

A value of null, or an empty string, indicates that cross-domain requests cannot be accepted with any HTTP method. This means that CORS is effectively disabled.

The asterisk (*) character is a wildcard and indicates that cross-domain requests can be accepted using any HTTP method. The use of wildcards is not recommended. For more information, see the caution above.

CorsOrigins

A comma-separated list of domains from which CORS requests may originate. The originating browser should automatically send the domain in the HTTP Origin header of the cross-domain request. PI Web API inspects the Origin header of the request against the list of allowed origins to make an authorization decision.

The default value, null or an empty string, indicates that cross-domain requests cannot be accepted from any origin. This means that CORS is effectively disabled.

The asterisk (*) character is a wildcard and indicates that cross-domain requests can be accepted from any origin. The use of wildcards is not recommended. For more information, see the caution above.

CorsExposedHeaders

A comma-separated list of HTTP response headers that browsers are allowed to access, in addition to the simple response headers that are exposed by the browser by default. The following simple response headers are available by default:

• Cache-Control

• Content-Language

• Content-Type

• Expires

• Last-Modified

• Pragma

To make other headers available to an application, include them in a list after the CorsExposedHeaders attribute. For example, if you are creating an element using CreateElement and would like to obtain the URL resource for the newly created element from the Location header, specify the Location header explicitly in CorsExposedHeaders.

CorsSupportsCredentials

A Boolean property that indicates whether the browser can send and receive authentication information along with a cross-origin request and response.

The default value, false, means that authentication information is not sent with the request and will not be accepted in the response. If you are running PI Web API with an authentication type other than Anonymous, PI Web API returns a 401 Unauthorized response to cross-origin requests if the browser includes user credentials in the request.

The value true means that the browser can send authentication information with the request and receive it in the response. Per the CORS specification, CorsSupportsCredentials cannot be used in conjunction with a wildcard (*) value for CorsOrigins. The list of allowed origins must be explicitly defined when CorsSupportsCredentials is enabled.

PreflightMaxAge

You can configure PI Web API to indicate to client applications how long to cache the preflight request. Set to -1 to never send an Access-Control-Max-Age header in the preflight response. Set to 0 to instruct the client to never cache the preflight response.