--- title: Enable Cross-Origin Requests (CORS) in ASP.NET Core author: rick-anderson description: Learn how CORS as a standard for allowing or rejecting cross-origin requests in an ASP.NET Core app. ms.author: riande ms.custom: mvc ms.date: 09/05/2018 uid: security/cors --- # Enable Cross-Origin Requests (CORS) in ASP.NET Core By [Mike Wasson](https://github.com/mikewasson), [Shayne Boyer](https://twitter.com/spboyer), and [Tom Dykstra](https://github.com/tdykstra) Browser security prevents a web page from making requests to a different domain than the one that served the web page. This restriction is called the *same-origin policy*. The same-origin policy prevents a malicious site from reading sensitive data from another site. Sometimes, you might want to allow other sites make cross-origin requests to your app. [Cross Origin Resource Sharing](https://www.w3.org/TR/cors/) (CORS) is a W3C standard that allows a server to relax the same-origin policy. Using CORS, a server can explicitly allow some cross-origin requests while rejecting others. CORS is safer and more flexible than earlier techniques, such as [JSONP](https://wikipedia.org/wiki/JSONP). This topic shows how to enable CORS in an ASP.NET Core app. ## Same origin Two URLs have the same origin if they have identical schemes, hosts, and ports ([RFC 6454](https://tools.ietf.org/html/rfc6454)). These two URLs have the same origin: * `https://example.com/foo.html` * `https://example.com/bar.html` These URLs have different origins than the previous two URLs: * `https://example.net` – Different domain * `https://www.example.com/foo.html` – Different subdomain * `http://example.com/foo.html` – Different scheme * `https://example.com:9000/foo.html` – Different port > [!NOTE] > Internet Explorer doesn't consider the port when comparing origins. ## Register CORS services ::: moniker range=">= aspnetcore-2.1" Reference the [Microsoft.AspNetCore.App metapackage](xref:fundamentals/metapackage-app) or add a package reference to the [Microsoft.AspNetCore.Cors](https://www.nuget.org/packages/Microsoft.AspNetCore.Cors/) package. ::: moniker-end ::: moniker range="= aspnetcore-2.0" Reference the [Microsoft.AspNetCore.All metapackage](xref:fundamentals/metapackage) or add a package reference to the [Microsoft.AspNetCore.Cors](https://www.nuget.org/packages/Microsoft.AspNetCore.Cors/) package. ::: moniker-end ::: moniker range="< aspnetcore-2.0" Add a package reference to the [Microsoft.AspNetCore.Cors](https://www.nuget.org/packages/Microsoft.AspNetCore.Cors/) package. ::: moniker-end Call in `Startup.ConfigureServices` to add CORS services to the app's service container: [!code-csharp[](cors/sample/CorsExample1/Startup.cs?name=snippet_addcors&highlight=3)] ## Enable CORS After registering CORS services, use either of the following approaches to enable CORS in an ASP.NET Core app: * [CORS Middleware](#enable-cors-with-cors-middleware) – Apply CORS policies globally to the app via middleware. * [CORS in MVC](#enable-cors-in-mvc) – Apply CORS policies per action or per controller. CORS Middleware isn't used. ### Enable CORS with CORS Middleware CORS Middleware handles cross-origin requests to the app. To enable CORS Middleware in the request processing pipeline, call the extension method in `Startup.Configure`. CORS Middleware must precede any defined endpoints in your app where you want to support cross-origin requests (for example, before the call to `UseMvc` for MVC/Razor Pages Middleware). A *cross-origin policy* can be specified when adding the CORS Middleware using the class. There are two approaches for defining a CORS policy: * Call `UseCors` with a lambda: [!code-csharp[](cors/sample/CorsExample1/Startup.cs?highlight=11,12&range=22-38)] The lambda takes a object. [Configuration options](#cors-policy-options), such as `WithOrigins`, are described later in this topic. In the preceding example, the policy allows cross-origin requests from `https://example.com` and no other origins. The URL must be specified without a trailing slash (`/`). If the URL terminates with `/`, the comparison returns `false` and no header is returned. `CorsPolicyBuilder` has a fluent API, so you can chain method calls: [!code-csharp[](cors/sample/CorsExample3/Startup.cs?highlight=2-3&range=29-32)] * Define one or more named CORS policies and select the policy by name at runtime. The following example adds a user-defined CORS policy named *AllowSpecificOrigin*. To select the policy, pass the name to `UseCors`: [!code-csharp[](cors/sample/CorsExample2/Startup.cs?name=snippet_begin&highlight=5-6,21)] ### Enable CORS in MVC You can alternatively use MVC to apply specific CORS policies per action or per controller. When using MVC to enable CORS, the registered CORS services are used. The CORS Middleware isn't used. ### Per action To specify a CORS policy for a specific action, add the [[EnableCors]](xref:Microsoft.AspNetCore.Cors.EnableCorsAttribute) attribute to the action. Specify the policy name. [!code-csharp[](cors/sample/CorsMVC/Controllers/ValuesController.cs?name=EnableOnAction&highlight=2)] ### Per controller To specify the CORS policy for a specific controller, add the [[EnableCors]](xref:Microsoft.AspNetCore.Cors.EnableCorsAttribute) attribute to the controller class. Specify the policy name. [!code-csharp[](cors/sample/CorsMVC/Controllers/ValuesController.cs?name=EnableOnController&highlight=2)] The precedence order is: 1. action 1. controller ### Disable CORS To disable CORS for a controller or action, use the [[DisableCors]](xref:Microsoft.AspNetCore.Cors.DisableCorsAttribute) attribute: [!code-csharp[](cors/sample/CorsMVC/Controllers/ValuesController.cs?name=DisableOnAction&highlight=2)] ## CORS policy options This section describes the various options that you can set in a CORS policy. * [Set the allowed origins](#set-the-allowed-origins) * [Set the allowed HTTP methods](#set-the-allowed-http-methods) * [Set the allowed request headers](#set-the-allowed-request-headers) * [Set the exposed response headers](#set-the-exposed-response-headers) * [Credentials in cross-origin requests](#credentials-in-cross-origin-requests) * [Set the preflight expiration time](#set-the-preflight-expiration-time) For some options, it may be helpful to read the [How CORS works](#how-cors-works) section first. ### Set the allowed origins To allow one or more specific origins, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=20-24&highlight=4)] To allow all origins, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=28-32&highlight=4)] Consider carefully before allowing requests from any origin. Allowing requests from any origin means that *any website* can make cross-origin requests to your app. This setting affects [preflight requests and the Access-Control-Allow-Origin header](#preflight-requests) (described later in this topic). ### Set the allowed HTTP methods To allow all HTTP methods, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=45-50&highlight=5)] This setting affects [preflight requests and the Access-Control-Allow-Methods header](#preflight-requests) (described later in this topic). ### Set the allowed request headers To allow specific headers to be sent in a CORS request, called *author request headers*, call and specify the allowed headers: [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=54-59&highlight=5)] To allow all author request headers, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=63-68&highlight=5)] This setting affects [preflight requests and the Access-Control-Request-Headers header](#preflight-requests) (described later in this topic). ::: moniker range=">= aspnetcore-2.2" A CORS Middleware policy match to specific headers specified by `WithHeaders` is only possible when the headers sent in `Access-Control-Request-Headers` exactly match the headers stated in `WithHeaders`. For instance, consider an app configured as follows: ```csharp app.UseCors(policy => policy.WithHeaders(HeaderNames.CacheControl)); ``` CORS Middleware declines a preflight request with the following request header because `Content-Language` ([HeaderNames.ContentLanguage](xref:Microsoft.Net.Http.Headers.HeaderNames.ContentLanguage)) isn't listed in `WithHeaders`: ``` Access-Control-Request-Headers: Cache-Control, Content-Language ``` The app returns a *200 OK* response but doesn't send the CORS headers back. Therefore, the browser doesn't attempt the cross-origin request. ::: moniker-end ::: moniker range="< aspnetcore-2.2" CORS Middleware always allows four headers in the `Access-Control-Request-Headers` to be sent regardless of the values configured in CorsPolicy.Headers. This list of headers includes: * `Accept` * `Accept-Language` * `Content-Language` * `Origin` For instance, consider an app configured as follows: ```csharp app.UseCors(policy => policy.WithHeaders(HeaderNames.CacheControl)); ``` CORS Middleware responds successfully to a preflight request with the following request header because `Content-Language` is always whitelisted: ``` Access-Control-Request-Headers: Cache-Control, Content-Language ``` ::: moniker-end ### Set the exposed response headers By default, the browser doesn't expose all of the response headers to the app. For more information, see [W3C Cross-Origin Resource Sharing (Terminology): Simple Response Header](https://www.w3.org/TR/cors/#simple-response-header). The response headers that are available by default are: * `Cache-Control` * `Content-Language` * `Content-Type` * `Expires` * `Last-Modified` * `Pragma` The CORS specification calls these headers *simple response headers*. To make other headers available to the app, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=72-77&highlight=5)] ### Credentials in cross-origin requests Credentials require special handling in a CORS request. By default, the browser doesn't send credentials with a cross-origin request. Credentials include cookies and HTTP authentication schemes. To send credentials with a cross-origin request, the client must set `XMLHttpRequest.withCredentials` to `true`. Using `XMLHttpRequest` directly: ```javascript var xhr = new XMLHttpRequest(); xhr.open('get', 'https://www.example.com/api/test'); xhr.withCredentials = true; ``` In jQuery: ```jQuery $.ajax({ type: 'get', url: 'https://www.example.com/home', xhrFields: { withCredentials: true } ``` In addition, the server must allow the credentials. To allow cross-origin credentials, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=81-86&highlight=5)] The HTTP response includes an `Access-Control-Allow-Credentials` header, which tells the browser that the server allows credentials for a cross-origin request. If the browser sends credentials but the response doesn't include a valid `Access-Control-Allow-Credentials` header, the browser doesn't expose the response to the app, and the cross-origin request fails. Be careful when allowing cross-origin credentials. A website at another domain can send a signed-in user's credentials to the app on the user's behalf without the user's knowledge. The CORS specification also states that setting origins to `"*"` (all origins) is invalid if the `Access-Control-Allow-Credentials` header is present. ### Preflight requests For some CORS requests, the browser sends an additional request before making the actual request. This request is called a *preflight request*. The browser can skip the preflight request if the following conditions are true: * The request method is GET, HEAD, or POST. * The app doesn't set request headers other than `Accept`, `Accept-Language`, `Content-Language`, `Content-Type`, or `Last-Event-ID`. * The `Content-Type` header, if set, has one of the one of the following values: * `application/x-www-form-urlencoded` * `multipart/form-data` * `text/plain` The rule on request headers set for the client request applies to headers that the app sets by calling `setRequestHeader` on the `XMLHttpRequest` object. The CORS specification calls these headers *author request headers*. The rule doesn't apply to headers the browser can set, such as `User-Agent`, `Host`, or `Content-Length`. The following is an example of a preflight request: ``` OPTIONS https://myservice.azurewebsites.net/api/test HTTP/1.1 Accept: */* Origin: https://myclient.azurewebsites.net Access-Control-Request-Method: PUT Access-Control-Request-Headers: accept, x-my-custom-header Accept-Encoding: gzip, deflate User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0) Host: myservice.azurewebsites.net Content-Length: 0 ``` The pre-flight request uses the HTTP OPTIONS method. It includes two special headers: * `Access-Control-Request-Method`: The HTTP method that will be used for the actual request. * `Access-Control-Request-Headers`: A list of request headers that the app sets on the actual request. As stated earlier, this doesn't include headers that the browser sets, such as `User-Agent`. A CORS preflight request might include an `Access-Control-Request-Headers` header, which indicates to the server the headers that are sent with the actual request. To allow specific headers, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=54-59&highlight=5)] To allow all author request headers, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=63-68&highlight=5)] Browsers aren't entirely consistent in how they set `Access-Control-Request-Headers`. If you set headers to anything other than `"*"` (or use ), you should include at least `Accept`, `Content-Type`, and `Origin`, plus any custom headers that you want to support. The following is an example response to the preflight request (assuming that the server allows the request): ``` HTTP/1.1 200 OK Cache-Control: no-cache Pragma: no-cache Content-Length: 0 Access-Control-Allow-Origin: https://myclient.azurewebsites.net Access-Control-Allow-Headers: x-my-custom-header Access-Control-Allow-Methods: PUT Date: Wed, 20 May 2015 06:33:22 GMT ``` The response includes an `Access-Control-Allow-Methods` header that lists the allowed methods and optionally an `Access-Control-Allow-Headers` header, which lists the allowed headers. If the preflight request succeeds, the browser sends the actual request. If the preflight request is denied, the app returns a *200 OK* response but doesn't send the CORS headers back. Therefore, the browser doesn't attempt the cross-origin request. ### Set the preflight expiration time The `Access-Control-Max-Age` header specifies how long the response to the preflight request can be cached. To set this header, call : [!code-csharp[](cors/sample/CorsExample4/Startup.cs?range=90-95&highlight=5)] ## How CORS works This section describes what happens in a CORS request at the level of the HTTP messages. It's important to understand how CORS works so that the CORS policy can be configured correctly and debugged when unexpected behaviors occur. The CORS specification introduces several new HTTP headers that enable cross-origin requests. If a browser supports CORS, it sets these headers automatically for cross-origin requests. Custom JavaScript code isn't required to enable CORS. The following is an example of a cross-origin request. The `Origin` header provides the domain of the site that's making the request: ``` GET https://myservice.azurewebsites.net/api/test HTTP/1.1 Referer: https://myclient.azurewebsites.net/ Accept: */* Accept-Language: en-US Origin: https://myclient.azurewebsites.net Accept-Encoding: gzip, deflate User-Agent: Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0) Host: myservice.azurewebsites.net ``` If the server allows the request, it sets the `Access-Control-Allow-Origin` header in the response. The value of this header either matches the `Origin` header from the request or is the wildcard value `"*"`, meaning that any origin is allowed: ``` HTTP/1.1 200 OK Cache-Control: no-cache Pragma: no-cache Content-Type: text/plain; charset=utf-8 Access-Control-Allow-Origin: https://myclient.azurewebsites.net Date: Wed, 20 May 2015 06:27:30 GMT Content-Length: 12 Test message ``` If the response doesn't include the `Access-Control-Allow-Origin` header, the cross-origin request fails. Specifically, the browser disallows the request. Even if the server returns a successful response, the browser doesn't make the response available to the client app. ## Additional resources * [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/docs/Web/HTTP/CORS)