14. Introducing CORS

CORS, or “Cross-origin resource sharing” allows a resource such as a web page running JavaScript inside a browser, to make AJAX requests (XMLHttpRequests) to a different domain, without compromising the security of either party.

A typical use case is to have a static website hosted on a CDN make requests to another resource, such as a hosted CouchDB instance. This avoids needing an intermediary proxy, using JSONP or similar workarounds to retrieve and host content.

While CouchDB’s integrated HTTP server and support for document attachments makes this less of a constraint for pure Couch projects, there are many cases where separating the static content from the database access is desirable, and CORS makes this very straightforwards indeed.

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.

CORS support is provided as experimental functionality in 1.3.0, and as such will need to be enabled specifically in CouchDB’s configuration.

New in version 1.3.0: added CORS support see JIRA COUCHDB-431

14.1. 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

14.2. Configuration

14.2.1. 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 = *

14.2.2. Passing Credentials

By default, neither authentication headers nor cookies are included in requests and responses. To do so requires both setting XmlHttpRequest.withCredentials = true on the request object in the browser, and additionally enabling it within CouchDB.

[cors]
credentials = true

CouchDB will respond to a credentials-enabled CORS request with an additional header, Access-Control-Allow-Credentials=true.

14.2.3. Tightening Access

14.2.3.1. Restricting by Protocol, Host and optional Port

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

14.2.3.2. Restricting Accepted Methods

Methods may be further restricted. These apply to all CORS-enabled instances.

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

14.2.4. Configuration per vhost

All the above parameters origins, methods, headers, credentials may be individually configured per CouchDB vhost. For example, the configuration section for http://example.com/ would be contained in:

[cors:http://example.com]
credentials = false
origins = *
methods = GET, PUT, HEAD

14.2.5. Useful References

Standards and References:

Mozilla Developer Network Resources:

Client-side CORS support and usage: