Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 7F54CD001 for ; Fri, 14 Dec 2012 02:03:27 +0000 (UTC) Received: (qmail 53350 invoked by uid 500); 14 Dec 2012 02:03:27 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 53318 invoked by uid 500); 14 Dec 2012 02:03:27 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 53307 invoked by uid 99); 14 Dec 2012 02:03:27 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 14 Dec 2012 02:03:27 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 1FFFA81C5C3; Fri, 14 Dec 2012 02:03:27 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: dch@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [1/3] git commit: Docs: add notes on CORS functionality Message-Id: <20121214020327.1FFFA81C5C3@tyr.zones.apache.org> Date: Fri, 14 Dec 2012 02:03:27 +0000 (UTC) Updated Branches: refs/heads/master 6c3c7b83a -> cc35be3b6 Docs: add notes on CORS functionality Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/cc35be3b Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/cc35be3b Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/cc35be3b Branch: refs/heads/master Commit: cc35be3b6fa0bc1eefe4954793131ef3541b47da Parents: 8f326c6 Author: Dave Cottlehuber Authored: Thu Dec 13 16:47:12 2012 +0100 Committer: Dave Cottlehuber Committed: Fri Dec 14 03:02:55 2012 +0100 ---------------------------------------------------------------------- share/doc/build/Makefile.am | 3 + share/doc/src/changelog.rst | 2 - share/doc/src/config_reference.rst | 29 ++++++ share/doc/src/cors.rst | 153 +++++++++++++++++++++++++++++++ share/doc/src/index.rst | 1 + 5 files changed, 186 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/cc35be3b/share/doc/build/Makefile.am ---------------------------------------------------------------------- diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am index e06b21a..3db9689 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 \ http://git-wip-us.apache.org/repos/asf/couchdb/blob/cc35be3b/share/doc/src/changelog.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/changelog.rst b/share/doc/src/changelog.rst index 18c19d4..55ab002 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 ^^^^^^^^^^^^^ http://git-wip-us.apache.org/repos/asf/couchdb/blob/cc35be3b/share/doc/src/config_reference.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/config_reference.rst b/share/doc/src/config_reference.rst index b2e78cf..7ae761a 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]` http://git-wip-us.apache.org/repos/asf/couchdb/blob/cc35be3b/share/doc/src/cors.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/cors.rst b/share/doc/src/cors.rst new file mode 100644 index 0000000..ff85dd9 --- /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 `_ + +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://git-wip-us.apache.org/repos/asf/couchdb/blob/cc35be3b/share/doc/src/index.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst index ad3a90d..70d1b9e 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