CORS Filter

原文来自：CORS Filter

CORS Filter是适用于支持Java web应用跨源资源共享（CORS）的首个统一解决方案。而跨源资源共享（CORS）是W3C近期一直致力于引入的保障从web浏览器到处理请求的服务器之间跨域请求的标准化机制。

早期web浏览器为防止用户秘密信息泄露给第三方不同程度强制推行同源策略。同源策略在2000年早期转换为创新性XMLHttpRequest。然而现代web应用增长性的寻求动态集成来自第三方的组件和服务，这一需求最初只能通过“黑客”似的方法例如“JSONP”。CORS的提出主要为识别跨域请求的标准化，推动互联网向前发展。

CORS原理：主要包含两个功能方面：从浏览器脚本方面 VS. 从web Service方面。

从浏览器脚本放面：通过严格控制交换数据的类型来允许跨域请求。除非是由XHR作者发起的特定请求，且允许跨域web服务，否则 Cookies等数据将被锁。如此就减轻了数据泄露的风险。

从web Service的方法：通过利用浏览器报告的源URL，目标跨域web Service能够基于自己的源策略确定是否允许还是拒绝本次请求。

完整的CORS说明详见：https://www.w3.org/TR/cors/。

注意为使CORS正常工作，浏览器和web服务器必须都支持CORS机制。

注意：CORS并不是致力于提供服务端的安全，浏览器提供源请求头，而服务器无法直接验证。

目前主流浏览器都支持CORS：

部分通过XDomainRequest对象支持，要想支持集成完整的CORS在通用XMLHttpRequest 对象上，需要IE10以上内核版本。

CORS Filter可以以插件形式集成在任何标准的Java Servlet容器上，以处理服务器上servlets、JSPs以及HTML等文件收到的跨站请求。

CORS Filter实现标准的Javax.servlet.Filter接口，拦截进入的HTTP请求，如果识别出该请求为跨域的，则向请求中加入适用的CORS策略和header信息，然后再将该HTTP请求传递给真正的请求目标（包括servlets、JSPs、静态XML/HTML文档等。）

CORS Filter的透明本质使之易于改进已有的Java Web Service具有跨源资源共享（CORS）能力。只需要将CORS JAR文件添加到你的CLASSPATH上并通过在你的web.xml文件中加入几行XML代码来使该文件能够被service找到并调用即可。CORS Filter实现十分高效，之友33kb。

CORS Filter安装：CORS Filter可以运行于能够兼容Java Servlet 3.0以上版本的任何web容器，例如最受欢迎的开源Apache Tomcat服务器容器。安装只需要简单三步。

首先：从CORS Filters下载cors-filter-<version>.jar文件及其java-property-utils-<version>.jar依赖文件，并将它们添加到你的web server

因为我用的maven，这两个jar包已经引入在Java Resources/Libraries/Maven Dependencies里面了。

Maven项目的CORS配置方法是将如下依赖添加到project的pom.xml文件中：

<dependency><groupId>com.thetransactioncompany</groupId><artifactId>cors-filter</artifactId><version>${cors.filter.version}</version>
        <scope>runtime</scope></dependency>
其次：将CORS配置信息添加到web.xml文档中：打开src/main/webapp/WEB-INF/web.xml文件，向其中添加CORS Filter声明和映射，其中XML声明为：
<filter>
<filter-name>CORS</filter-name>
<filter-class>com.thetransactioncompany.cors.CORSFilter</filter-class>
<async-supported>true</async-supported> 
        <!-- filter supports asynchronous processing -->
<!-- Enable CORS for REST HTTP methods -->
<init-param>
<param-name>cors.supportedMethods</param-name>
<param-value>GET,PUT,POST,DELETE,HEAD,OPTIONS</param-value>
</init-param>
</filter>
如需使用能够自动哦那个检测配置文件变化并进行重配置的CORS Filter变异版本，可以使用下面的<filter-class>：

<filter-class>com.thetransactioncompany.cors.autoreconf.AutoReconfigurableCORSFilter</filter-class>

然后需要声明一个filter映射，以告诉web服务器哪些servlet或URL允许接受跨域请求。可以通过servlet名指定单一servlet，也可以通过“/*”指定应用CORS Filter应用于全部web app和URL。
<filter-mapping>
<filter-name>CORS</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
更完整的web.xml文件配置模板（包括param详情）详见web.xml.txt，而本文前面举例的配置只配置了CORS所支持的访问方法的配置。

配置完毕后需重启web server。

注意：默认情况是CORS Filter采用public access的跨源资源共享策略，允许通过包括用户凭据/cookies在内安全机制的全部跨站请求。这一默认配置其实适用于大多数情况，因为CORS本来就不是以增强服务端安全性为主要目标的；CORS的基本意向是保护浏览器端的数据安全，即保护浏览器上合法运行的JavaScript应用及其用户凭据信息例如cookies数据不会泄露。

如有特殊需求需要修改CORS Filter行为，参考下面的CORS Filter配置指导。

CORS Filter配置：多数情况下CORS Filter不需要额外配置就能在大多数情况下直接运行。它的默认配置是public模式，通知浏览器如下事项：

• 对来自任何源的请求都应接受；
• 请求可能包含任何自定义请求头信息；
• 请求可能包含如cookies的凭据信息。

如果默认的public模式的CORS 不能满足你的需求，可以通过自定义配置修改默认配置。目前支持两种配置格式：

• Java属性text文档；
• web应用描述器WEB-INF/web.xml文档中定义的Filter<init-params>标签。

CORS Filter采用如下优先顺序解析配置属性：

如果定义从引用位置（必须是web应用根路径相关的例如/WEB-INF/cors.properties或相关的classpath）加载CORS Filter属性文件，首先检查cors.configurationFile系统属性，忽略取默认值的配置属性。

其次检查一个filter的<init-param> cors.configurationFile，忽略取默认值的属性。

最后检查filter init-params节的CORS配置属性，忽略取默认值的配置属性。

可配参数属性包括：

cors.allowGenericHttpRequests：取值范围{true|false}，默认true。true表示通用HTTP请求将被允许传递给filter；false表示只有经过验证的且接受CORS的请求可以传递给filter。

cors.allowOrigin：取值范围{*|origin-list}，默认*。*表示接受来自任何源的请求，而空格分隔的origin-list注意泪出CORS filter允许接受的请求源，如果请求源不再列表中，将获得HTTP 403 “Forbidden”响应。

cors.allowSubdomains：取值范围{true|false}，默认false。true表示接受来自允许的origin-list列表中域名的子域名范围内的请求。子域名判断是通过比较语法和前缀（主机名、IP地址、可选端口号等）。例如，如果上一项cors.allowOrigin属性的配置中origin-list包含http://example.com，且本属性cors.allowSubdomains设置为true，则来自诸如下列表：

http://www.example.comhttp://foo.example.comhttp://bar.example.com

的请求都将被允许接受。而来自不匹配源：

http://www.example.com:8080https://foo.example.comhttp://myexample.com

的请求将不允许接受：

cors.supportedMethods：取值范围{method-list}，默认“GET, POST, HEAD, OPTIONS”。列举所支持的HTTP方法。该信息将通过“Access-Control-Allow-Methods”头信息返回给调用者，并且需要在service中实现CORS。非列表内的方法类型的请求将被CORS filters以HTTP 405 “Method not allowed”响应拒绝。

cors.supportedHeaders：取值范围{*|header-list}，默认*。定义所支持的自定义请求头，其信息将通过“Access-Control-Allow-Headers”头信息返回给请求者。如果配置为*，则包含任何自定义请求头信息的请求都将被接受。CORS Filter对此的实现是简单打包请求全部信息返回给浏览器。自定义请求头是指由浏览器JavaScript应用通过XMLHttpRequest.setRequestHeader()方法。例如通知浏览器允许“Content-Type, X-Requested-With”请求头。

cors.exposedHeaders：取值{header-list}，默认空表。列出浏览器通过XMLHttpRequest.getResponseHeader()方法可以暴露哪些header详细信息（而非简要信息）给跨域请求。CORS Filter通过“Access-Control-Expose-Headers”头提供这类信息详情，通知浏览器例如“X-Custom-1, X-Custom-2”自定义头信息可以安全的保留给初始化跨域请求的脚本。

cors.supportsCredentials：取值{true|false}，默认true。提示所支持的用户凭据类型，如cookies、HTTP授权或客户端证书。CORS Filter利用该值构造“Access-Control-Allow-Credentials”头信息。

cors.maxAge：取值{int}，默认-1（未定义）。定义web浏览器可以缓存预检请求结果的时间长度，单位为秒。如果值为-1，表示未定义。该信息通过“Access-Control-Max-Age”头信息传递给浏览器。建议浏览器保存预检请求缓存1小时，即该属性值为3600.

cors.tagRequests：取值{true|false}，默认false（不标记，或没有标签）。允许HTTP servlet请求标记提供给下游处理程序的CORS信息。允许标记只需将该属性值配置为true。

配置完毕后，需重启web应用或服务器，以使配置生效。