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 thelocal.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]
¶ 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 anAccept
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
, thecouch_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 thecouch_httpd_auth/users_db_public
option totrue
(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 thecouch_httpd_auth/secret
andcouch_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 thecouch_httpd_auth/proxy_use_secret
option is nottrue
. 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 theauthentication 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:
- The Consumer secret:
[oauth_consumer_secrets] consumer1 = sekr1t
- Token secrets:
[oauth_token_secrets] token1 = tokensekr1t
- A mapping from tokens to users:
[oauth_token_users] token1 = couchdb_username