diff options
author | Dave Cottlehuber <dch@apache.org> | 2012-12-13 16:47:12 +0100 |
---|---|---|
committer | Dave Cottlehuber <dch@apache.org> | 2012-12-14 03:02:55 +0100 |
commit | cc35be3b6fa0bc1eefe4954793131ef3541b47da (patch) | |
tree | 1c9664d36fa3627cc1fb0caf1fe508e27771a0c4 | |
parent | 8f326c6b6e238337b2af79dca17b3cd38f62d1aa (diff) | |
download | couchdb-cc35be3b6fa0bc1eefe4954793131ef3541b47da.tar.gz |
Docs: add notes on CORS functionality
-rw-r--r-- | share/doc/build/Makefile.am | 3 | ||||
-rw-r--r-- | share/doc/src/changelog.rst | 2 | ||||
-rw-r--r-- | share/doc/src/config_reference.rst | 29 | ||||
-rw-r--r-- | share/doc/src/cors.rst | 153 | ||||
-rw-r--r-- | share/doc/src/index.rst | 1 |
5 files changed, 186 insertions, 2 deletions
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am index e06b21af7..3db9689c7 100644 --- a/share/doc/build/Makefile.am +++ b/share/doc/build/Makefile.am @@ -58,6 +58,7 @@ html_files = \ html/_sources/changelog.txt \ html/_sources/changes.txt \ html/_sources/commonjs.txt \ + html/_sources/cors.txt \ html/_sources/config_reference.txt \ html/_sources/configuring.txt \ html/_sources/ddocs.txt \ @@ -109,6 +110,7 @@ html_files = \ html/changelog.html \ html/changes.html \ html/commonjs.html \ + html/cors.html \ html/config_reference.html \ html/configuring.html \ html/ddocs.html \ @@ -159,6 +161,7 @@ src_files = \ ../src/changelog.rst \ ../src/changes.rst \ ../src/commonjs.rst \ + ../src/cors.rst \ ../src/config_reference.rst \ ../src/configuring.rst \ ../src/ddocs.rst \ diff --git a/share/doc/src/changelog.rst b/share/doc/src/changelog.rst index 18c19d40c..55ab00204 100644 --- a/share/doc/src/changelog.rst +++ b/share/doc/src/changelog.rst @@ -16,8 +16,6 @@ Apache CouchDB CHANGES Version 1.3.0 ------------- -.. note:: This version has not been released yet. - Database core ^^^^^^^^^^^^^ diff --git a/share/doc/src/config_reference.rst b/share/doc/src/config_reference.rst index b2e78cf3b..7ae761ab9 100644 --- a/share/doc/src/config_reference.rst +++ b/share/doc/src/config_reference.rst @@ -50,6 +50,8 @@ Configuration Groups +----------------------------------+-------------------------------------------+ | uuids | UUID generation options | +----------------------------------+-------------------------------------------+ +| cors | Cross Origin Resource Sharing settings | ++----------------------------------+-------------------------------------------+ attachments Configuration Options --------------------------------- @@ -172,6 +174,8 @@ httpd Configuration Options +--------------------------------------+---------------------------------------+ | vhost_global_handlers | vhost_global_handlers | +--------------------------------------+---------------------------------------+ +| enable_cors | enables CORS functionality when true | ++--------------------------------------+---------------------------------------+ httpd_design_handlers Configuration Options ------------------------------------------- @@ -286,3 +290,28 @@ uuids Configuration Options +======================================+=======================================+ | algorithm | algorithm | +--------------------------------------+---------------------------------------+ + + +cors Configuration Options +--------------------------- + ++--------------------------------------+---------------------------------------+ +| Option | Description | ++======================================+=======================================+ +| origins | List of origins, separated by a comma | +| | (protocol, host, optional port) | ++--------------------------------------+---------------------------------------+ +| methods | accepted HTTP methods | ++--------------------------------------+---------------------------------------+ +| credentials | `true` sends additional header | +| | Access-Control-Allow-Credentials=true | ++--------------------------------------+---------------------------------------+ + +Note that `credentials=true` and `origins=*` are mutually exclusive. + +cors vhost Configuration +------------------------ + +The same configuration options for `cors` overall may be applied to an +individual vhost, within a specific section header, for `example.com` the +appropriate section would be: `[cors:http://example.com]` diff --git a/share/doc/src/cors.rst b/share/doc/src/cors.rst new file mode 100644 index 000000000..ff85dd95c --- /dev/null +++ b/share/doc/src/cors.rst @@ -0,0 +1,153 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _cors: + +================ +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. + +.. versionadded:: 1.3.0 added CORS support see JIRA :issue:`431` + +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. + +.. code-block:: ini + + [httpd] + enable_cors = true + + [cors] + origins = * + +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. + +.. code-block:: ini + + [cors] + credentials = true + +CouchDB will respond to a credentials-enabled CORS request with an +additional header, `Access-Control-Allow-Credentials=true`. + +Tightening Access +----------------- + +Restricting by Protocol, Host and optional Port +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: ini + + [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 + +Restricting Accepted Methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Methods may be further restricted. These apply to all CORS-enabled instances. + +.. code-block:: ini + + [cors] + ; List of accepted methods, comma-separated + ; refer to http://tools.ietf.org/html/rfc2616, rfc2817, rfc5789 + methods = GET, POST, PUT, DELETE + + +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: + +.. code-block:: ini + + [cors:http://example.com] + credentials = false + origins = * + methods = GET, PUT, HEAD + +Useful References +----------------- + +- Original JIRA `implementation ticket <https://issues.apache.org/jira/browse/COUCHDB-431>`_ + +Standards and References: + +- IETF RFCs relating to methods `rfc2618 <http://tools.ietf.org/html/rfc2616>`_, + `rfc2817 <http://tools.ietf.org/html/rfc2817>`_, and + `rfc5789 <http://tools.ietf.org/html/rfc5789>`_. +- IETF RFC for `Web Origins <http://tools.ietf.org/html/rfc6454>`_ +- W3C `CORS standard <http://www.w3.org/TR/cors>`_ + +Mozilla Developer Network Resources: + +- `Same origin policy for URIs <https://developer.mozilla.org/en-US/docs/Same-origin_policy_for_file:_URIs>`_ +- `HTTP Access Control <https://developer.mozilla.org/En/HTTP_access_control>`_ +- `Server-side Access Control <https://developer.mozilla.org/En/Server-Side_Access_Control>`_ +- `Javascript same origin policy <https://developer.mozilla.org/en-US/docs/Same_origin_policy_for_JavaScript>`_ + + +Client-side CORS support and usage: + +- `CORS browser support matrix <http://caniuse.com/cors>`_ +- `COS tutorial <http://www.html5rocks.com/en/tutorials/cors/>`_ +- `<http://hacks.mozilla.org/2009/07/cross-site-xmlhttprequest-with-cors/>`_ + diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst index ad3a90d17..70d1b9eac 100644 --- a/share/doc/src/index.rst +++ b/share/doc/src/index.rst @@ -40,6 +40,7 @@ Contents ddocs query-servers commonjs + cors errors changes release |