### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »

# 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

- Original JIRA implementation ticket

Standards and References:

- IETF RFCs relating to methods rfc2618, rfc2817, and rfc5789.
- IETF RFC for Web Origins
- W3C CORS standard

Mozilla Developer Network Resources:

- Same origin policy for URIs
- HTTP Access Control
- Server-side Access Control
- Javascript same origin policy

Client-side CORS support and usage:

- CORS browser support matrix
- COS tutorial
- http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/

### Navigation

- index
- next |
- previous |
- Apache CouchDB 1.3 Manual »