3.4. Authentication and Authorization

3.4.1. Server Administrators

[admins]

A default CouchDB install provides admin-level access to all connecting users. This configuration is known as Admin Party, and is not recommended for in-production usage. You can crash the party simply by creating the first admin account. CouchDB server administrators and passwords are not stored in the _users database, but in the local.ini file, which should be appropriately secured and readable only by system administrators:

[admins]
;admin = mysecretpassword
admin = -hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90
architect = -pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000

Administrators can be added directly to the [admins] section, and when CouchDB is restarted, the passwords will be salted and encrypted. You may also use the HTTP interface to create administrator accounts; this way, you don’t need to restart CouchDB, and there’s no need to temporarily store or transmit passwords in plaintext. The HTTP _config/admins endpoint supports querying, deleting or creating new admin accounts:

GET /_config/admins HTTP/1.1
Accept: application/json
Host: localhost:5984

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 196
Content-Type: application/json
Date: Fri, 30 Nov 2012 11:37:18 GMT
Server: CouchDB (Erlang/OTP)

{
  "admin": "-hashed-6d3c30241ba0aaa4e16c6ea99224f915687ed8cd,7f4a3e05e0cbc6f48a0035e3508eef90",
  "architect": "-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"
}

If you already have a salted, encrypted password string (for example, from an old local.ini file, or from a different CouchDB server), then you can store the “raw” encrypted string, without having CouchDB doubly encrypt it.

PUT /_config/admins/architect?raw=true HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 89
Host: localhost:5984

"-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 89
Content-Type: application/json
Date: Fri, 30 Nov 2012 11:39:18 GMT
Server: CouchDB (Erlang/OTP)

"-pbkdf2-43ecbd256a70a3a2f7de40d2374b6c3002918834,921a12f74df0c1052b3e562a23cd227f,10000"

Further details are available in security, including configuring the work factor for PBKDF2, and the algorithm itself at PBKDF2 (RFC-2898).

Changed in version 1.4: PBKDF2 server-side hashed salted password support added, now as a synchronous call for the _config/admins API.

3.4.2. Authentication Configuration

[couch_httpd_auth]

allow_persistent_cookies

Makes cookies persistent if true.

[couch_httpd_auth]
allow_persistent_cookies = false

auth_cache_size

Number of User Context Object to cache in memory, to reduce disk lookups.

[couch_httpd_auth]
auth_cache_size = 50

authentication_db

Specifies the name of the system database for storing CouchDB users.

[couch_httpd_auth]
authentication_db = _users

Warning

If you change the database name, do not forget to remove or clean up the old database, since it will no longer be protected by CouchDB.

authentication_redirect

Specifies the location for redirection on successful authentication if a text/html response is accepted by the client (via an Accept header).

[couch_httpd_auth]
authentication_redirect = /_utils/session.html

iterations

New in version 1.3.

The number of iterations for password hashing by the PBKDF2 algorithm. A higher number provides better hash durability, but comes at a cost in performance for each request that requires authentication.

[couch_httpd_auth]
iterations = 10000

min_iterations

New in version 1.6.

The minimum number of iterations allowed for passwords hashed by the PBKDF2 algorithm. Any user with fewer iterations is forbidden.

[couch_httpd_auth]
min_iterations = 100

max_iterations

New in version 1.6.

The maximum number of iterations allowed for passwords hashed by the PBKDF2 algorithm. Any user with greater iterations is forbidden.

[couch_httpd_auth]
max_iterations = 100000

proxy_use_secret

When this option is set to true, the couch_httpd_auth/secret option is required for Proxy Authentication.

[couch_httpd_auth]
proxy_use_secret = false

public_fields

New in version 1.4.

A comma-separated list of field names in user documents (in couch_httpd_auth/authentication_db) that can be read by any user. If unset or not specified, authenticated users can only retrieve their own document.

[couch_httpd_auth]
public_fields = first_name, last_name, contacts, url

Note

Using the public_fields whitelist for user document properties requires setting the couch_httpd_auth/users_db_public option to true (the latter option has no other purpose):

[couch_httpd_auth]
users_db_public = true

require_valid_user

When this option is set to true, no requests are allowed from anonymous users. Everyone must be authenticated.

[couch_httpd_auth]
require_valid_user = false

secret

The secret token used for Proxy Authentication method.

[couch_httpd_auth]
secret = 92de07df7e7a3fe14808cef90a7cc0d91

timeout

Number of seconds since the last request before sessions will be expired.

[couch_httpd_auth]
timeout = 600

users_db_public

New in version 1.4.

Allow all users to view user documents. By default, only admins may browse all users documents, while users may browse only their own document.

[couch_httpd_auth]
users_db_public = false

x_auth_roles

The HTTP header name (X-Auth-CouchDB-Roles by default) that contains the list of a user’s roles, separated by a comma. Used for Proxy Authentication.

[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Roles

x_auth_token

The HTTP header name (X-Auth-CouchDB-Token by default) containing the token used to authenticate the authorization. This token is an HMAC-SHA1 created from the couch_httpd_auth/secret and couch_httpd_auth/x_auth_username. The secret key should be the same on the client and the CouchDB node. This token is optional if the value of the couch_httpd_auth/proxy_use_secret option is not true. Used for Proxy Authentication.

[couch_httpd_auth]
x_auth_roles = X-Auth-CouchDB-Token

x_auth_username

The HTTP header name (X-Auth-CouchDB-UserName by default) containing the username. Used for Proxy Authentication.

[couch_httpd_auth]
x_auth_username = X-Auth-CouchDB-UserName

3.4.3. HTTP OAuth Configuration

[couch_httpd_oauth]

New in version 1.2.

use_users_db

CouchDB is able to store OAuth credentials within user documents instead of config file by using this option:

[couch_httpd_oauth]
use_users_db = true

If set to true, OAuth token and consumer secrets will be looked up in the authentication database. These secrets are stored in a top level field named "oauth" in user documents, as below.

{
    "_id": "org.couchdb.user:joe",
    "type": "user",
    "name": "joe",
    "password_sha": "fe95df1ca59a9b567bdca5cbaf8412abd6e06121",
    "salt": "4e170ffeb6f34daecfd814dfb4001a73"
    "roles": ["foo", "bar"],
    "oauth": {
        "consumer_keys": {
            "consumerKey1": "key1Secret",
            "consumerKey2": "key2Secret"
        },
        "tokens": {
            "token1": "token1Secret",
            "token2": "token2Secret"
       }
    }
}

3.4.4. OAuth Configuration

[oauth_*]

To let users be authenticated by OAuth Authentication (RFC 5849), three special sections must be set up in the configuration file:

1. The Consumer secret:

[oauth_consumer_secrets]
consumer1 = sekr1t

2. Token secrets:

[oauth_token_secrets]
token1 = tokensekr1t

3. A mapping from tokens to users:

[oauth_token_users]
token1 = couchdb_username