.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Plack::Middleware::CrossOrigin 3pm" .TH Plack::Middleware::CrossOrigin 3pm "2020-08-20" "perl v5.30.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Plack::Middleware::CrossOrigin \- Adds headers to allow Cross\-Origin Resource Sharing .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 5 \& # Allow any WebDAV or standard HTTP request from any location. \& builder { \& enable \*(AqCrossOrigin\*(Aq, origins => \*(Aq*\*(Aq; \& $app; \& }; \& \& # Allow GET and POST requests from any location, cache results for 30 days. \& builder { \& enable \*(AqCrossOrigin\*(Aq, \& origins => \*(Aq*\*(Aq, methods => [\*(AqGET\*(Aq, \*(AqPOST\*(Aq], max_age => 60*60*24*30; \& $app; \& }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Adds Cross Origin Request Sharing headers used by modern browsers to allow \f(CW\*(C`XMLHttpRequest\*(C'\fR to work across domains. This module will also help protect against \s-1CSRF\s0 attacks in some browsers. .PP This module attempts to fully conform to the \s-1CORS\s0 spec, while allowing additional flexibility in the values specified for the of the headers. .PP The module also ensures that the response contains a \f(CW\*(C`Vary: Origin\*(C'\fR header to avoid potential issues with caches. .SH "CORS REQUESTS IN BRIEF" .IX Header "CORS REQUESTS IN BRIEF" There are two types of \s-1CORS\s0 requests. Simple requests, and preflighted requests. .SS "Simple Requests" .IX Subsection "Simple Requests" A simple request is one that could be generated by a standard \s-1HTML\s0 form. Either a \f(CW\*(C`GET\*(C'\fR or \f(CW\*(C`POST\*(C'\fR request, with no additional headers. For these requests, the server processes the request as normal, and attaches the correct \s-1CORS\s0 headers in the response. The browser then decides based on those headers whether to allow the client script access to the response. .SS "Preflighted Requests" .IX Subsection "Preflighted Requests" If additional headers are specified, or a method other than \f(CW\*(C`GET\*(C'\fR or \f(CW\*(C`POST\*(C'\fR 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. .SH "CSRF Protection" .IX Header "CSRF Protection" Some browsers will also provide same headers with cross domain \&\f(CW\*(C`POST\*(C'\fR requests from \s-1HTML\s0 forms. These requests will also be checked against the allowed origins and rejected before they reach the rest of your Plack application. .SH "CONFIGURATION" .IX Header "CONFIGURATION" .IP "origins" 8 .IX Item "origins" A list of allowed origins. Origins should be formatted as a \s-1URL\s0 scheme and host, with no path information. (\f(CW\*(C`http://www.example.com\*(C'\fR) \&'\f(CW\*(C`*\*(C'\fR' can be specified to allow access from any location. Wildcards (\f(CW\*(C`*\*(C'\fR) can also be included in in the host to match any part of a host name (e.g. \f(CW\*(C`https://*.example.com\*(C'\fR). At least one origin must bust be specified for this middleware to have any effect. This will be matched against the \&\f(CW\*(C`Origin\*(C'\fR request header, and will control the \f(CW\*(C`Access\-Control\-Allow\-Origin\*(C'\fR response header. If the origin does not match, the request is aborted. .IP "headers" 8 .IX Item "headers" A list of allowed request headers. '\f(CW\*(C`*\*(C'\fR' can be specified to allow any headers. Controls the \f(CW\*(C`Access\-Control\-Allow\-Headers\*(C'\fR response header. Includes a set of headers by default to simplify working with WebDAV and \s-1AJAX\s0 frameworks: .RS 8 .IP "\(bu" 4 \&\f(CW\*(C`Cache\-Control\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`Depth\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`If\-Modified\-Since\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`User\-Agent\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`X\-File\-Name\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`X\-File\-Size\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`X\-Prototype\-Version\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`X\-Requested\-With\*(C'\fR .RE .RS 8 .RE .IP "methods" 8 .IX Item "methods" A list of allowed methods. '\f(CW\*(C`*\*(C'\fR' can be specified to allow any methods. Controls the \f(CW\*(C`Access\-Control\-Allow\-Methods\*(C'\fR response header. Defaults to all of the standard \s-1HTTP\s0 and WebDAV methods. .IP "max_age" 8 .IX Item "max_age" The max length in seconds to cache the response data for. Controls the \f(CW\*(C`Access\-Control\-Max\-Age\*(C'\fR response header. If not specified, the web browser will decide how long to use. .IP "expose_headers" 8 .IX Item "expose_headers" A list of allowed headers to expose to the client. '\f(CW\*(C`*\*(C'\fR' can be specified to allow the browser to see all of the response headers. Controls the \f(CW\*(C`Access\-Control\-Expose\-Headers\*(C'\fR response header. .IP "credentials" 8 .IX Item "credentials" Whether the resource will be allowed with user credentials (cookies, \&\s-1HTTP\s0 authentication, and client-side \s-1SSL\s0 certificates) supplied. Controls the \f(CW\*(C`Access\-Control\-Allow\-Credentials\*(C'\fR response header. .IP "continue_on_failure" 8 .IX Item "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 \s-1CORS\s0 headers will be added to the response. This matches how non-allowed requests would be handled if this module was not used at all. .Sp This disables the \s-1CSRF\s0 protection and is not recommended. It could be needed for applications that need to allow cross-origin \s-1HTML\s0 form \f(CW\*(C`POST\*(C'\fRs without whitelisting domains. .SH "BROWSER SUPPORT" .IX Header "BROWSER SUPPORT" Different browsers have different levels of support for \s-1CORS\s0 headers. .IP "Gecko (Firefox, Seamonkey)" 8 .IX Item "Gecko (Firefox, Seamonkey)" Initially supported in Gecko 1.9.1 (Firefox 3.5). Supports the complete \s-1CORS\s0 spec for \f(CW\*(C`XMLHttpRequest\*(C'\fRs. .Sp Does not yet provide the \f(CW\*(C`Origin\*(C'\fR header for \s-1CSRF\s0 protection (Bugzilla #446344 ). .IP "WebKit (Safari, Google Chrome)" 8 .IX Item "WebKit (Safari, Google Chrome)" Initially supported in Safari 4 and Chrome 3. Supports the complete \&\s-1CORS\s0 spec. .Sp The \f(CW\*(C`expose_headers\*(C'\fR 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 \f(CW\*(C`Referer\*(C'\fR header). .Sp Also provides the \f(CW\*(C`Origin\*(C'\fR header for \s-1CSRF\s0 protection starting with WebKit v528.5 (Chrome 2, Safari 4). .IP "Internet Explorer" 8 .IX Item "Internet Explorer" Initially supported in \s-1IE8.\s0 Not supported with the standard \&\f(CW\*(C`XMLHttpRequest\*(C'\fR object. A separate object, \f(CW\*(C`XDomainRequest\*(C'\fR, must be used. Only \f(CW\*(C`GET\*(C'\fR and \f(CW\*(C`POST\*(C'\fR methods are allowed. No extra headers can be added to the request. Neither the status code or any headers aside from \f(CW\*(C`Content\-Type\*(C'\fR can be retrieved from the response. .Sp \&\s-1IE10\s0 supports \s-1CORS\s0 via the standard \f(CW\*(C`XMLHttpRequest\*(C'\fR object. .IP "Opera" 8 .IX Item "Opera" Opera and Opera Mobile support \s-1CORS\s0 since version 12. .SH "SEE ALSO" .IX Header "SEE ALSO" .SS "\s-1CORS\s0 Resources" .IX Subsection "CORS Resources" .IP "\(bu" 4 W3C Spec for Cross-Origin Resource Sharing .IP "\(bu" 4 W3C Spec for Cross-Origin Resource Sharing \- Implementation Considerations .IP "\(bu" 4 Mozilla Developer Center \- \s-1HTTP\s0 Access Control .IP "\(bu" 4 Mozilla Developer Center \- Server-Side Access Control .IP "\(bu" 4 Cross browser examples of using \s-1CORS\s0 requests .IP "\(bu" 4 \&\s-1MSDN\s0 \- XDomainRequest Object .IP "\(bu" 4 XDomainRequest \- Restrictions, Limitations and Workarounds .IP "\(bu" 4 Wikipedia \- Cross-Origin Resource Sharing .IP "\(bu" 4 \&\s-1CORS\s0 advocacy .SS "\s-1CSRF\s0 Resources" .IX Subsection "CSRF Resources" .IP "\(bu" 4 Wikipedia \- Cross-site request forgery .IP "\(bu" 4 Stanford Web Security Research \- Cross-Site Request Forgery .IP "\(bu" 4 WebKit Bugzilla \- Add origin header to \s-1POST\s0 requests .IP "\(bu" 4 Mozilla Bugzilla \- Implement Origin header \s-1CSRF\s0 mitigation .SS "Related Technologies" .IX Subsection "Related Technologies" .IP "\(bu" 4 Cross-domain policy file for Flash .IP "\(bu" 4 Wikipedia \- \s-1JSONP\s0 .SH "AUTHOR" .IX Header "AUTHOR" Graham Knop .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2011 by Graham Knop. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. .SH "AUTHOR" .IX Header "AUTHOR" haarg \- Graham Knop (cpan:HAARG) .SS "\s-1CONTRIBUTORS\s0" .IX Subsection "CONTRIBUTORS" None so far. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2011 the Plack::Middleware::CrossOrigin \*(L"\s-1AUTHOR\*(R"\s0 and \&\*(L"\s-1CONTRIBUTORS\*(R"\s0 as listed above. .SH "LICENSE" .IX Header "LICENSE" This library is free software and may be distributed under the same terms as perl itself.