Security Features Overview

An overview of security features focusing on what CouchDB provides out of the box.


CouchDB ships with basic authentication that compares user credentials to Admin accounts. See Setting up an Admin account for more details.

You can specify a custom authentication handler and the web authentication scheme in the configuration file. The example below specifies that CouchDB will use the default_authentication_handler method defined in the [WWW] couch_httpd module:

authentication_handler = {couch_httpd, default_authentication_handler}
WWW-Authenticate = Basic realm="administrator"

Other notes: The "null_authentication_handler" in "couch_httpd" allows any user credentials to run as admin. Web servers such as Apache or Nginx can also provide an authentication layer as a reverse-proxy to CouchDB.


CouchDB supports one role, the "admin" group, which can execute any of the HTTP API on any database in the CouchDB instance. See Setting up an Admin account for more details.

CouchDB does not support other roles at this time. Support for read access restriction is planned for the 1.0 release.


A design document may define a member function called "validate_doc_update". Requests to create or update a document are validated against every "validate_doc_update" function defined in the database. The validation functions are executed in an unspecified order. A design document can contain only one validation function. Errors are thrown as javascript objects.

Example of a design document that validates the presence of an "address" field and returns :

   _id: "_design/myview",
   validate_doc_update: "function(newDoc, oldDoc, userCtx) {
      if(newDoc.address === undefined) {
         throw {missing_field: 'Document must have an address.'};

The result of a document update without the address field will look like this:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="administrator"
Server: CouchDB/0.9.0 (Erlang OTP/R12B)
Date: Tue, 21 Apr 2009 00:02:32 GMT
Content-Type: text/plain;charset=utf-8
Content-Length: 57
Cache-Control: must-revalidate

{"error":"missing_field","reason":"Document must have an address."} 

The "validate_doc_update" function accepts three arguments:

  1. newDoc - The document to be created or used for update.

  2. oldDoc - The current document if document id was specified in the HTTP request

  3. userCtx - User context object, which contains three properties:

    1. db - String name of database

    2. name - String user name

    3. roles - Array of roles to which user belongs. Currently only admin role is supported.

last edited 2009-04-21 00:24:29 by SamuelWan