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 9EB28DF84 for ; Mon, 20 May 2013 16:38:14 +0000 (UTC) Received: (qmail 36649 invoked by uid 500); 20 May 2013 16:31:36 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 31583 invoked by uid 500); 20 May 2013 16:30:40 -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 15393 invoked by uid 99); 20 May 2013 16:27:03 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 20 May 2013 16:27:03 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 289758902ED; Mon, 20 May 2013 16:27:02 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: djc@apache.org To: commits@couchdb.apache.org Date: Mon, 20 May 2013 16:27:03 -0000 Message-Id: <99ca04605b44493ebfb21d64ed59bb57@git.apache.org> In-Reply-To: <478a74d8570a4769835f80e3bc741542@git.apache.org> References: <478a74d8570a4769835f80e3bc741542@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [2/6] git commit: updated refs/heads/1.3.x to b03809c docs: fold section on CORS into configuration chapter Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/3c0287cc Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/3c0287cc Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/3c0287cc Branch: refs/heads/1.3.x Commit: 3c0287cc95e5f7d27ab1445ad494f380eae57b56 Parents: 866c8eb Author: Dirkjan Ochtman Authored: Mon May 20 18:10:48 2013 +0200 Committer: Dirkjan Ochtman Committed: Mon May 20 18:10:48 2013 +0200 ---------------------------------------------------------------------- share/doc/build/Makefile.am | 3 - share/doc/src/configuring.rst | 139 ++++++++++++++++++++++++++++++++ share/doc/src/cors.rst | 153 ------------------------------------ share/doc/src/index.rst | 1 - 4 files changed, 139 insertions(+), 157 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/3c0287cc/share/doc/build/Makefile.am ---------------------------------------------------------------------- diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am index ee5a4eb..fc2524a 100644 --- a/share/doc/build/Makefile.am +++ b/share/doc/build/Makefile.am @@ -57,7 +57,6 @@ 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 \ @@ -103,7 +102,6 @@ html_files = \ html/changelog.html \ html/changes.html \ html/commonjs.html \ - html/cors.html \ html/config_reference.html \ html/configuring.html \ html/ddocs.html \ @@ -148,7 +146,6 @@ 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/3c0287cc/share/doc/src/configuring.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/configuring.rst b/share/doc/src/configuring.rst index 138bce9..245e29a 100644 --- a/share/doc/src/configuring.rst +++ b/share/doc/src/configuring.rst @@ -467,3 +467,142 @@ such as Lucene: request URL to be interpreted as ``http://couchdb:5984/media``. Care should be taken to ensure that both requested URLs and destination URLs are able to cope. + +.. _cors: + +Cross-Origin Resource Sharing +============================= + +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/3c0287cc/share/doc/src/cors.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/cors.rst b/share/doc/src/cors.rst deleted file mode 100644 index ff85dd9..0000000 --- a/share/doc/src/cors.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. 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/3c0287cc/share/doc/src/index.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst index 43ec938..b1c6feb 100644 --- a/share/doc/src/index.rst +++ b/share/doc/src/index.rst @@ -35,7 +35,6 @@ Contents ddocs query-servers commonjs - cors errors changes release