ASP.NET Web API自身对CORS的支持: CORS授权检验的实施

通过《EnableCorsAttribute特性背后的故事》我们知道：由CorsPolicyProvider提供的CorsPolicy表示目标Action采用的资源授权策略，ASP.NET Web API最终需要利用它对具体的跨域资源请求实施授权检验并生成相应的CORS响应报头。在ASP.NET Web API的应用编程接口中，资源授权检验的结果通过类型CorsResult来表示。

一、CorsResult

CorsResult定义在命名空间“System.Web.Cors”下，表示资源提供者针对具体跨域资源请求进行授权检验得到的结果，最终写入响应的CORS报头均通过此对象来生成。如下面的代码片断所示，CorsResult依然具有与6个CORS响应报头对应的属性，通过其方法ToResponseHeaders方法的字典表示由此6个属性生成的CORS相应报头，字典对象的Key和Value分别表示报头名称和值。

public class CorsResult
{
    public string            AllowedOrigin { get; set; }
    public IList<string>     AllowedExposedHeaders { get; }
    public IList<string>     AllowedHeaders { get; }
    public IList<string>     AllowedMethods { get; }
    public long?             PreflightMaxAge { get; set; }
    public bool              SupportsCredentials { get; set; }

    public IList<string>     ErrorMessages { get; }
    public bool              IsValid { get; }

    public virtual IDictionary<string, string> ToResponseHeaders();
}

CorsResult具有一个布尔类型的属性IsValid表示请求是否通过资源授权检验。如果该属性返回False（没有通过资源授权检验），另一个相关的属性ErrorMessages会提供导致检验失败的原因。IsValid是一个只读属性，它的值取决于通过ErrorMessages属性表示的字符串列表是否为空。

二、CorsRequestContext

针对CORS的支持其实并不限于仅被使用在ASP.NET Web API上，用于根据提供的资源授权策略对跨域资源请求进行授权检验得引擎定义在程序集System.Web.Cors.dll中，定义在另一个程序集对于这些类型来说，除了CorsPolicy定义在程序集System.Web.Cors.dll，其余的类型均定义在程序集System.Web.Http.Cors.dll中的相关类型可以视为对这个核心CORS引擎的扩展。对于本节引入的类型来说，它具有的命名空间其实也体现了它所在的程序集。

对于ASP.NET Web API来说，CORS资源授权检验实施的目标是表示当请求的HttpRequestMessage对象，这个对象自然不可能使用在ASP.NET的核心CORS引擎中。对于后者，授权检验是针对一个System.Web.Cors.CorsRequestContext对象，它代表针对当前请求的上下文。如下面的代码片断所示，我们可以通过CorsRequestContext对象得到对应HTTP请求的地址（RequestUri）、主机名称（Host）和采用的HTTP方法（HttpMethod）。

public class CorsRequestContext
{
    public Uri         RequestUri { get; set; }
    public string      Host { get; set; }
    public string      HttpMethod { get; set; }

    public string          Origin { get; set; }
    public bool            IsPreflight { get; }
    public string          AccessControlRequestMethod { get; set; }
    public ISet<string>    AccessControlRequestHeaders { get; }

    public IDictionary<string, object> Properties { get; }
}

CorsRequestContext的Origin属性返回通过请求的“Origin”报头表示的源站点。我们可以利用其IsPreflight属性判断HTTP请求是否为一个预检请求，这里对预检请求的判断标准与我们前面演示实例采用的完全一致：采用HTTP-OPTIONS方法摒弃同时具有“Origin”和“Access-Control-Request-Method”报头。

对于针对预检请求的CorsRequestContext，我们可以通过其属性AccessControlRequestMethod和AccessControlRequestHeaders得到请求报头“Access-Control-Request-Method”和“Access-Control-Request-Headers”的值。通过另一个字典类型的只读属性Properties，我们可以将任意对象作为属性附加到该CorsRequestContext对象上。

三、CorsEngine

我们说ASP.NET 的核心CORS引擎定义在程序集System.Web.Cors.dll中，它主要体验为这个名为CorsEngine的对象，其主要的使命在于：根据提供的资源授权策略（通过CorsPolicy类型表示）针对具体的跨域资源请求（通过CorsRequestContext类型表示）实施授权检验并得到相应的授权结果（通过CorsResult表示）。所有的CorsEngine类型均实现System.Web.Cors.ICorsEngine接口，如下面的代码片断所示，跨域资源请求的授权检查就实现在其唯一的EvaluatePolicy方法中。

public interface ICorsEngine
{
    CorsResult EvaluatePolicy(CorsRequestContext requestContext, CorsPolicy policy);
}

在程序集System.Web.Cors.dll中定义了唯一的实现了ICorsEngine接口，即具有如下定义的类型System.Web.Cors.CorsEngine。如下面的代码片断所示，CorsEngine类型定义了3个辅助的虚方法（TryValidateOrigin、TryValidateMethod 和TryValidateHeaders）分别针对请求的源站点以及请求采用的HTTP方法和自定义报头实施授权检验，其中后面两个方法是专门为预检请求设计的。

public class CorsEngine : ICorsEngine
{
    public virtual CorsResult EvaluatePolicy(CorsRequestContext requestContext, CorsPolicy policy);

    public virtual bool TryValidateOrigin(CorsRequestContext requestContext, CorsPolicy policy, CorsResult result);
    public virtual bool TryValidateMethod(CorsRequestContext requestContext, CorsPolicy policy, CorsResult result);
    public virtual bool TryValidateHeaders(CorsRequestContext requestContext, CorsPolicy policy, CorsResult result);
}

CorsPolicyProviderFactory一样，ASP.NET Web API使用的CorsEngine需要注册到当前HttpConfiguration，注册的CorsEngine同样是被添加到HttpConfiguration的属性字典之中。CorsEngine的注册可以通过调用HttpConfiguration如下所示的扩展方法SetCorsEngine来完成。另一个扩展方法GetCorsEngine用于获取注册的CorsEngine，如果在调用此方法时CorsEngine尚未被注册，一个CorsEngine对象会被创建出来并自动注册到HttpConfiguration上。

public static class CorsHttpConfigurationExtensions
{
    //其他成员
    public static void SetCorsEngine(this HttpConfiguration httpConfiguration, ICorsEngine corsEngine);
    public static ICorsEngine GetCorsEngine(this HttpConfiguration httpConfiguration);
}

 

CORS系列文章
[1] 同源策略与JSONP
[2] 利用扩展让ASP.NET Web API支持JSONP
[3] W3C的CORS规范
[4] 利用扩展让ASP.NET Web API支持CORS
[5] ASP.NET Web API自身对CORS的支持: 从实例开始
[6] ASP.NET Web API自身对CORS的支持: CORS授权策略的定义和提供
[7] ASP.NET Web API自身对CORS的支持: CORS授权检验的实施
[8] ASP.NET Web API自身对CORS的支持: CorsMessageHandler