CORS support for ASP.NET Web API
Overview
Cross-origin resource sharing (CORS) is a standard that allows web pages to make AJAX requests to another domain. It relaxes the same-origin policy implemented on the web browsers that limits the calls to be within the same domain.
The CORS spec (http://www.w3.org/TR/cors/) defines the way how the server and browser interact in order to make cross origin calls. Most of the modern browsers today already support CORS. Our goal is to enable the support for our Web API services.
Scenarios
Enabling CORS
We’ve added a new extension method to the HttpConfiguration to enable CORS. With this, you can enable the support globally, per controller or per action.
Globally
You can define a global setting when calling EnableCors. For example, the following will enable CORS globally, allowing all origins, methods, and headers. There’re many settings on the EnableCorsAttribute that you can configure which we will see later.
using System.Web.Http.Cors; publicstaticclass WebApiConfig { publicstaticvoid Register(HttpConfiguration config) { // other settings removed for clarity config.EnableCors(new EnableCorsAttribute()); } }
Per Controller
The support can also be scoped to the controller. First you just need to call EnableCors without providing a global setting.
using System.Web.Http.Cors; publicstaticclass WebApiConfig { publicstaticvoid Register(HttpConfiguration config) { // other settings removed for clarity config.EnableCors(); } }
Then you can declare the EnableCorsAttribute on the controller to enable CORS.
[EnableCors] publicclass ValuesController : ApiController { public IEnumerable<string> Get() { returnnewstring[] { "value1", "value2" }; } publicstring Get(int id) { return"value "+ id; } }
Per Action
In a similar fashion, you can enable CORS on a single action by first calling EnableCors.
using System.Web.Http.Cors; publicstaticclass WebApiConfig { publicstaticvoid Register(HttpConfiguration config) { // other settings removed for clarity config.EnableCors(); } }
And then declare the EnableCorsAttribute on an action.
publicclass ValuesController : ApiController { public IEnumerable<string> Get() { returnnewstring[] { "value1", "value2" }; } [EnableCors] publicstring Get(int id) { return"value "+ id; } }
Attribute precedence
When you have the EnableCorsAttribute applied on all scopes (globally, per-controller, per-action), the closest one to the resource wins. Therefore the precedence is defined as follows:
- Action
- Controller
- Global
Excluding a controller or an action from EnableCors
You can use [DisableCors] attribute to exclude a controller or and action from the global or per-controller settings. For example, the following will enable CORS for all the actions in the ValuesController except for Get(int id).
[EnableCors] publicclass ValuesController : ApiController { public IEnumerable<string> Get() { returnnewstring[] { "value1", "value2" }; } [DisableCors] publicstring Get(int id) { return"value "+ id; } }
Configuring [EnableCors] attribute
There’re few settings under the EnableCorsAttribute. These settings are defined by the CORS spec (http://www.w3.org/TR/cors/#resource-processing-model).
- Origins
- Headers
- Methods
- ExposedHeaders
- SupportsCredentials
- PreflightMaxAge
By default, EnableCorsAttribute will allow all origins, methods and headers. Note that when you declare the attribute on an action it automatically assumes the HTTP Method of the action that you declared on.
As soon as you specify the origins, you are basically limiting the access to the specified origins. The same applies to the methods and the headers.
For example, the following will only allow “http://localhost” and “http://sample.com” to access the ValuesController from the browser though AJAX. Note that it is still allowing any methods and headers because they’re not specified.
[EnableCors(Origins = new[] { "http://localhost", "http://sample.com" })] publicclass ValuesController : ApiController { public IEnumerable<string> Get() { returnnewstring[] { "value1", "value2" }; } publicstring Get(int id) { return"value "+ id; } }
Implementing a custom ICorsPolicyProvider
You can implement ICorsPolicyProvider to load the CORS settings/policy dynamically from other sources such as web.config or database. In fact, both the EnableCorsAttribute and DisableCorsAttribute implement this interface internally.
namespace System.Web.Http.Cors
{
public interface ICorsPolicyProvider
{
Task GetCorsPolicyAsync(HttpRequestMessage request);
}
}Note that the ICorsPolicyProvider is async so that we don’t block the thread on I/O.
Sample
Here is a custom implementation of ICorsPolicyProvider that loads the origins from web.config.
[AttributeUsage(AttributeTargets.Method | AttributeTargets.Class, AllowMultiple = false)] publicclass EnableCorsAppSettingsAttribute : Attribute, ICorsPolicyProvider { private CorsPolicy _policy; public EnableCorsAppSettingsAttribute(string appSettingOriginKey) { _policy = new CorsPolicy { AllowAnyMethod = true, AllowAnyHeader = true }; // loads the origins from AppSettingsstring originsString = ConfigurationManager.AppSettings[appSettingOriginKey]; if (!String.IsNullOrEmpty(originsString)) { foreach (var origin in originsString.Split(',')) { _policy.Origins.Add(origin); } } } public Task<CorsPolicy> GetCorsPolicyAsync(HttpRequestMessage request) { return Task.FromResult(_policy); } }
You can apply it on the controller/action just like EnableCorsAttribute.
[EnableCorsAppSettings("internal:origins")] publicclass ValuesController : ApiController { public IEnumerable<string> Get() { returnnewstring[] { "value1", "value2" }; } publicstring Get(int id) { return"value "+ id; } }
And it will read the “internal:origins” appSetting from the web.config.
<appSettings><addkey="webpages:Version"value="2.0.0.0"/><addkey="webpages:Enabled"value="false"/><addkey="PreserveLoginUrl"value="true"/><addkey="ClientValidationEnabled"value="true"/><addkey="UnobtrusiveJavaScriptEnabled"value="true"/><addkey="internal:origins"value="http://example.com,http://webapisample.azurewebsites.net"/></appSettings>
Implementing a custom ICorsPolicyProviderFactory
ICorsPolicyProviderFactory is an abstraction that allows you to specify how the ICorsPolicyProvider are retrieved. By default we provide the AttributeBasedPolicyProviderFactory which allows you to specify the ICorsPolicyProvider as attributes ([EnableCors], [DisableCors]). However you can extend the ICorsPolicyProviderFactory to create a centralized configuration model.
namespace System.Web.Http.Cors { publicinterface ICorsPolicyProviderFactory { ICorsPolicyProvider GetCorsPolicyProvider(HttpRequestMessage request); } }
You can register the custom ICorsPolicyProviderFactory through SetCorsPolicyProviderFactory extension method.
publicstaticclass HttpConfigurationExtensions { // other extensions removed for claritypublicstaticvoid SetCorsPolicyProviderFactory(this HttpConfiguration httpConfiguration, ICorsPolicyProviderFactory corsPolicyProviderFactory); }
Sample
Here is a custom implementation of ICorsPolicyProviderFactory that allows you to configure the CORS settings through your own CorsConfiguration class instead of attributes.
publicclass ConfigBasedPolicyProviderFactory : ICorsPolicyProviderFactory { private CorsConfiguration _configuration; public ConfigBasedPolicyProviderFactory(CorsConfiguration configuration) { _configuration = configuration; } public ICorsPolicyProvider GetCorsPolicyProvider(HttpRequestMessage request) { var routeData = request.GetRouteData(); if (routeData == null || !routeData.Values.Keys.Contains("controller")) { returnnull; } var controller = routeData.Values["controller"] asstring; return _configuration.GetPolicyForRequest(controller); } }
publicclass CorsConfiguration { private Dictionary<string, EnableCorsAttribute> _settings = new Dictionary<string, EnableCorsAttribute>(); publicvoid AddSetting(string controller, EnableCorsAttribute policyProvider) { _settings.Add(controller, policyProvider); } publicvirtual EnableCorsAttribute GetPolicyForRequest(string controller) { EnableCorsAttribute policyProvider; _settings.TryGetValue(controller, out policyProvider); return policyProvider; } }
Once the ConfigBasedPolicyProviderFactory is registered, it will enable CORS on ValuesController and UsersController.
CorsConfiguration corsConfig = new CorsConfiguration(); corsConfig.AddSetting("Values", new EnableCorsAttribute()); corsConfig.AddSetting("Users", new EnableCorsAttribute { Origins = new[] { "http://localhost" } }); config.SetCorsPolicyProviderFactory(new ConfigBasedPolicyProviderFactory(corsConfig)); config.EnableCors();