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
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 = *
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.
[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
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
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
Standards and References:
Mozilla Developer Network Resources:
Client-side CORS support and usage: