Plack::Middleware::CrossOrigin - Adds headers to allow Cross-Origin Resource Sharing
version 0.009
# Allow any WebDAV or standard HTTP request from any location. builder { enable 'CrossOrigin', origins => '*'; $app; }; # Allow GET and POST requests from any location, cache results for 30 days. builder { enable 'CrossOrigin', origins => '*', methods => ['GET', 'POST'], max_age => 60*60*24*30; $app; };
Adds Cross Origin Request Sharing headers used by modern browsers to allow XMLHttpRequest to work across domains. This module will also help protect against CSRF attacks in some browsers.
XMLHttpRequest
This module attempts to fully conform to the CORS spec, while allowing additional flexibility in the values specified for the of the headers.
There are two types of CORS requests. Simple requests, and preflighted requests.
A simple request is one that could be generated by a standard HTML form. Either a GET or POST request, with no additional headers. For these requests, the server processes the request as normal, and attaches the correct CORS headers in the response. The browser then decides based on those headers whether to allow the client script access to the response.
GET
POST
If additional headers are specified, or a method other than GET or POST is used, the request must be preflighted. This means that the browser will first send a special request to the server to check if access is allowed. If the server allows it by responding with the correct headers, the actual request is then performed.
Some browsers will also provide same headers with cross domain POST requests from HTML forms. These requests will also be checked against the allowed origins and rejected before they reach the rest of your Plack application.
A list of allowed origins. Origins should be formatted as a URL scheme and host, with no path information. (http://www.example.com) '*' can be specified to allow access from any location. Must be specified for this middleware to have any effect. This will be matched against the Origin request header, and will control the Access-Control-Allow-Origin response header. If the origin does not match, the request is aborted.
http://www.example.com
*
Origin
Access-Control-Allow-Origin
A list of allowed request headers. '*' can be specified to allow any headers. Controls the Access-Control-Allow-Headers response header. Includes a set of headers by default to simplify working with WebDAV and AJAX frameworks:
Access-Control-Allow-Headers
Cache-Control
Depth
If-Modified-Since
User-Agent
X-File-Name
X-File-Size
X-Prototype-Version
X-Requested-With
A list of allowed methods. '*' can be specified to allow any methods. Controls the Access-Control-Allow-Methods response header. Defaults to all of the standard HTTP and WebDAV methods.
Access-Control-Allow-Methods
The max length in seconds to cache the response data for. Controls the Access-Control-Max-Age response header. If not specified, the web browser will decide how long to use.
Access-Control-Max-Age
A list of allowed headers to expose to the client. '*' can be specified to allow the browser to see all of the response headers. Controls the Access-Control-Expose-Headers response header.
Access-Control-Expose-Headers
Whether the resource will be allowed with user credentials (cookies, HTTP authentication, and client-side SSL certificates) supplied. Controls the Access-Control-Allow-Credentials response header.
Access-Control-Allow-Credentials
Normally, simple requests with an Origin that hasn't been allowed will be stopped before they continue to the main app. If this option is set, the request will be allowed to continue, but no CORS headers will be added to the response. This matches how non-allowed requests would be handled if this module was not used at all.
This disables the CSRF protection and is not recommended. It could be needed for applications that need to allow cross-origin HTML form POSTs without whitelisting domains.
Different browsers have different levels of support for CORS headers.
Initially supported in Gecko 1.9.1 (Firefox 3.5). Supports the complete CORS spec for XMLHttpRequests.
Does not yet provide the Origin header for CSRF protection (Bugzilla #446344).
Initially supported in Safari 4 and Chrome 3. Supports the complete CORS spec.
The expose_headers feature has been supported since WebKit v535.18 (Safari 6, Chrome 18). Preflighted requests were buggy prior to WebKit v534.19 (Safari 5.1, Chrome 11), but this module uses a workaround where possible (using the Referer header).
expose_headers
Referer
Also provides the Origin header for CSRF protection starting with WebKit v528.5 (Chrome 2, Safari 4).
Initially supported in IE8. Not supported with the standard XMLHttpRequest object. A separate object, XDomainRequest, must be used. Only GET and POST methods are allowed. No extra headers can be added to the request. Neither the status code or any headers aside from Content-Type can be retrieved from the response.
XDomainRequest
Content-Type
IE10 supports CORS via the standard XMLHttpRequest object.
Opera and Opera Mobile support CORS since version 12.
W3C Spec for Cross-Origin Resource Sharing
Mozilla Developer Center - HTTP Access Control
Mozilla Developer Center - Server-Side Access Control
Cross browser examples of using CORS requests
MSDN - XDomainRequest Object
XDomainRequest - Restrictions, Limitations and Workarounds
Wikipedia - Cross-Origin Resource Sharing
CORS advocacy
Wikipedia - Cross-site request forgery
Stanford Web Security Research - Cross-Site Request Forgery
WebKit Bugzilla - Add origin header to POST requests
Mozilla Bugzilla - Implement Origin header CSRF mitigation
Cross-domain policy file for Flash
Wikipedia - JSONP
Graham Knop <haarg@haarg.org>
This software is copyright (c) 2011 by Graham Knop.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Plack::Middleware::CrossOrigin, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Plack::Middleware::CrossOrigin
CPAN shell
perl -MCPAN -e shell install Plack::Middleware::CrossOrigin
For more information on module installation, please visit the detailed CPAN module installation guide.