What does _security secure in couchdb?

The database level security is controlled in couchdb by a special document called _security. The _security document is unique to every database. Let’s see what it looks like.

Taking an example from couchdb docs:-

    "admins": {
        "names": [
        "roles": [
    "members": {
        "names": [
        "roles": [

The construction of _security document

Every _security document[1] consists of two mandatory fields called admins and members. Both admins and members are json objects that in turn are made up of arrays called names and roles. The name in an admin or a member property must[2] be the name of the user stored in _users database. When couchdb authenticates a user from the _users database it can run checks[3] against the _security document of each database to determine whether the authenticated user is an admin or a member.

The roles property on the other hand is free form— meaning you can supply any value in the roles[4] array. What roles you choose would depend upon your application. If for example you are making an online library with couchdb you could use “librarian” and “reader” as roles. The significance of roles is that you can add role based checks in document validate functions and choose who updates what documents.

Difference between an admin and a member

An admin is authorized to perform CRUD on _design and _security documents.[5]

A member can only read or write normal documents— all documents except _design and the _security documents.[6]

Effect of adding a _security document

Once you add a _security to the database then the database can only be accessed by the person who is a part of the _security document. Any un-authorized person would be forbidden from accessing the database. [7]

So what does the _security secure?

The conclusion is pretty easy to draw. couchdb offers minimal read level security on the normal documents (that is all documents except the special _design and _security documents). Minimal because once you set either an admin or a member in the _security document then only the person that has been added to _security object can read from the database. But you can’t set conditional reading. Any member or any admin will be able to read all normal documents. That is there is no validate_on read function (In rcouch there is a validate_doc_read function). [8]

On the other hand couchdb offers full write level security. You can add conditional checks on who creates, updates or deletes a document using document update functions.

In short couchdb has two levels of security: –

the server level (which is set by the configuration files)

and the database level(which is set by the _security document)

The _security document consists of members and admins.

admins have the ability to write, read and update special documents of the database (_design and _security) where as the the members only have permission to read and write the normal documents (that is all documents except _design and _security).

Finally the write level protection can be enhanced by the use of document validate functions. [9]

Notes from Alexander

  1. They aren’t mandatory at all, just the ones which CouchDB handles in special way and requires them to have special structure.
  2. The “must” is too strong requirement. The name must be string, but it should point on some user name, which even may not exist at all. However, that would be a security leak.
  3. When user requests database or any it subresource, CouchDB checks his context (userCtx – a user name and list of their roles) against database _security.
  4. Any string value. In 1.3.0 we have dropped the support of non-string roles. That was bad hack.
  5. And run any IO-related tasks on database the admin, like compaction, running temporary views and views indexes cleanup.
  6. Members can read design documents, but not modify them. Same about _security one.
  7. Once you specify database members it becomes only accessible to those users or users with specified roles in additional to admin. Those who specified in admin are granted power to run IO operations upon database, manage _security and design documents.
  8. Same is above. _security members control global database read bit; _security admins controls exec bit for service operations and write bit for design docs and security.
  9. Correction: using validate document update functions. The update functions is a little bit different thing.

Thank you for proofreading this Alex 🙂

Two guys go to a bar…



  • On January 13, 2015