Differences between revisions 6 and 7
Revision 6 as of 2012-11-05 13:02:09
Size: 5561
Comment: added some more linkz
Revision 7 as of 2013-02-16 00:07:15
Size: 5785
Comment: make it painfully obvious
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:

Note: CORS is supported only in CouchDB 1.3.x branches or releases, and at present is experimental support. This means that:

 * functionality is disabled by default
 * support or API may change in subsequent releases

The official documentation has moved to http://docs.couchdb.org — The transition is not 100% complete, but http://docs.couchdb.org should be seen as having the latest info. In some cases, the wiki still has some more or older info on certain topics inside CouchDB.

You need to be added to the ContributorsGroup to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

Note: CORS is supported only in CouchDB 1.3.x branches or releases, and at present is experimental support. This means that:

  • functionality is disabled by default
  • support or API may change in subsequent releases

WARNING!! This page is a temporary gathering spot for CORS documentation while the git branch is in development. It will get merged back into the cors branch when sufficiently clean, and will use the sphinx support being worked on in the docs branch.

Introducing CORS

By supporting CORS functionality, a CouchDB instance can accept direct connections to protected DBs and instances, without the browser functionality being blocked due to the same origin constraint. CORS is widely supported today on over 90% of browsers.

Features

  • Simple requests for a couchdb instance
  • Preflight requests for a couchdb instance
  • Configuration for a specific CouchDB vhost
  • All origins are excluded by default

Configuration

Enabling CORS

To enable CORS support, you need to set the option enable_cors = true in the [httpd] section of local.ini, and [cors] section with origins = *. Note that by default, no origins are accepted, you must either use a wildcard or whitelist.

[httpd]
enable_cors = true

[cors]
origins = *

Tightening Access

Restricting by Protocol, Host and optional Port

[cors]
; List of origins, separated by a comma (protocol, host, port)
; refer to http://tools.ietf.org/html/rfc6454 for specification
origins = http://home.muse.net.nz:8000, https://localhost, http://www.number10.gov.uk:80

Restricting Accepted Methods

[cors]
; List of accepted methods, comma-separated
; refer to http://tools.ietf.org/html/rfc2616, rfc2817, rfc5789
methods = GET, POST, PUT, DELETE

Restricting Accepted Headers

[cors]
; List of accepted headers separated by a comma
headers = TODO

Securing at the VHOST level

TODO

To set the options for a vhost, you will need to create a section with the vhost name prefixed by "cors:" . Ex for the vhost example.com:

; Configuration for a vhost
;[cors:example.com]
; credentials = false
; List of origins separated by a comma
;origins =
; List of accepted headers separated by a comma
; headers =
; List of accepted methods
; methods =

Credentials

TODO

Testing Your Implementation

The following snippet was lifted from html5rocks CORS tutorial:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Testing CORS</title>
    <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
    <meta author="http://www.html5rocks.com/en/tutorials/cors/#toc-adding-cors-support-to-the-server">
    <meta license="Apache 2.0">
    <script>
      
      // Create the XHR object.
      function createCORSRequest(method, url) {
        var xhr = new XMLHttpRequest();
        if ("withCredentials" in xhr) {
          // XHR for Chrome/Firefox/Opera/Safari.
          xhr.open(method, url, true);
        } else if (typeof XDomainRequest != "undefined") {
          // XDomainRequest for IE.
          xhr = new XDomainRequest();
          xhr.open(method, url);
        } else {
          // CORS not supported.
          xhr = null;
        }
        return xhr;
      }

      // Make the actual CORS request.
      function makeCorsRequest(uri) {
        console.log("got uri: " + uri);
        var xhr = createCORSRequest('GET', uri);
        if (!xhr) {
          alert('CORS not supported');
          return;
        }

        // Response handlers.
        xhr.onload = function() {
          console.log('Response from CORS request to ' + uri + ': ' + xhr.responseText);
        };

        xhr.onerror = function() {
          console.log('Woops, there was an error making the request to ' + uri + '.');
        };

        xhr.send();
      }
      
      $(document).ready(function() {
        makeCorsRequest('http://my.couchdb.org:5984/');
        });
  </script>
  </head>
  <body>
  </body>
</html>

Reference Material

This image is from the excellent html5rocks CORS tutorial.

http://www.html5rocks.com/static/images/cors_flow.png

CORS References

Client-side CORS support and usage

Note that at least IE >= 8 does not support pre-flight.

CORS (last edited 2013-02-16 00:07:15 by DaveCottlehuber)