|
|
| |
Plack::Middleware::CrossOrigin(3) |
User Contributed Perl Documentation |
Plack::Middleware::CrossOrigin(3) |
Plack::Middleware::CrossOrigin - Adds headers to allow Cross-Origin Resource
Sharing
# 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.
This module attempts to fully conform to the CORS spec, while
allowing additional flexibility in the values specified for the of the
headers.
The module also ensures that the response contains a
"Vary: Origin" header to avoid potential
issues with caches.
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.
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.
- origins
- 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. Wildcards ("*") can
also be included in in the host to match any part of a host name (e.g.
"https://*.example.com"). At least one
origin must bust 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.
- headers
- 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:
- "Cache-Control"
- "Depth"
- "If-Modified-Since"
- "User-Agent"
- "X-File-Name"
- "X-File-Size"
- "X-Prototype-Version"
- "X-Requested-With"
- methods
- 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.
- max_age
- 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.
- expose_headers
- 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.
- credentials
- 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.
- continue_on_failure
- 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 "POST"s without whitelisting
domains.
Different browsers have different levels of support for CORS headers.
- Gecko (Firefox, Seamonkey)
- Initially supported in Gecko 1.9.1 (Firefox 3.5). Supports the complete
CORS spec for "XMLHttpRequest"s.
Does not yet provide the
"Origin" header for CSRF protection
(Bugzilla #446344
<https://bugzilla.mozilla.org/show_bug.cgi?id=446344>).
- WebKit (Safari, Google Chrome)
- 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).
Also provides the "Origin"
header for CSRF protection starting with WebKit v528.5 (Chrome 2, Safari
4).
- Internet Explorer
- 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.
IE10 supports CORS via the standard
"XMLHttpRequest" object.
- Opera
- Opera and Opera Mobile support CORS since version 12.
- W3C Spec for Cross-Origin Resource Sharing
<http://www.w3.org/TR/cors/>
- W3C Spec for Cross-Origin Resource Sharing - Implementation Considerations
<http://www.w3.org/TR/cors/#resource-implementation>
- Mozilla Developer Center - HTTP Access Control
<https://developer.mozilla.org/En/HTTP_access_control>
- Mozilla Developer Center - Server-Side Access Control
<https://developer.mozilla.org/En/Server-Side_Access_Control>
- Cross browser examples of using CORS requests
<http://www.nczonline.net/blog/2010/05/25/cross-domain-ajax-with-cross-origin-resource-sharing/>
- MSDN - XDomainRequest Object
<http://msdn.microsoft.com/en-us/library/cc288060%28v=vs.85%29.aspx>
- XDomainRequest - Restrictions, Limitations and Workarounds
<http://blogs.msdn.com/b/ieinternals/archive/2010/05/13/xdomainrequest-restrictions-limitations-and-workarounds.aspx>
- Wikipedia - Cross-Origin Resource Sharing
<http://en.wikipedia.org/wiki/Cross-Origin_Resource_Sharing>
- CORS advocacy <http://enable-cors.org/>
- Wikipedia - Cross-site request forgery
<http://en.wikipedia.org/wiki/Cross-site_request_forgery>
- Stanford Web Security Research - Cross-Site Request Forgery
<http://seclab.stanford.edu/websec/csrf/>
- WebKit Bugzilla - Add origin header to POST requests
<https://bugs.webkit.org/show_bug.cgi?id=20792>
- Mozilla Bugzilla - Implement Origin header CSRF mitigation
<https://bugzilla.mozilla.org/show_bug.cgi?id=446344>
- Cross-domain policy file for Flash
<http://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html>
- Wikipedia - JSONP <http://en.wikipedia.org/wiki/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.
haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
Copyright (c) 2011 the Plack::Middleware::CrossOrigin "AUTHOR" and
"CONTRIBUTORS" as listed above.
This library is free software and may be distributed under the same terms as
perl itself.
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc. |