4.6. Authentication and Authorization¶
4.6.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 last [admins] section that CouchDB finds when loading its ini files. See :config:intro for details on config file order and behaviour. This file (which could be something like etc/local.ini or etc/local.d/10-admins.ini on a Debian/Ubuntu system installed from packages) 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 /_node/{node-name}/_config/admins endpoint supports querying, deleting or creating new admin accounts: - GET /_node/nonode@nohost/_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 ini file, or from a different CouchDB server), then you can store the “raw” encrypted string, without having CouchDB doubly encrypt it. - PUT /_node/nonode@nohost/_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. 
4.6.2. Authentication Configuration¶
- [chttpd]¶
- require_valid_user¶
- When this option is set to true, no requests are allowed from anonymous users. Everyone must be authenticated. - [chttpd] require_valid_user = false - Note - This setting only affects the clustered-port (5984 by default). To make the same change for the node-local port (5986 by default), set the [couch_httpd_auth] setting of the same name. 
 
- [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_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 - Note - This setting affects both the clustered-port (5984 by default) and the node-local port (5986 by default). 
 - 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 couchdb/users_db_suffix) 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 - Warning - This setting only affects the node-local port (5986 by default). Most administrators want the [chttpd] setting of the same name for clustered-port (5984) behaviour. 
 - secret¶
- The secret token is used for Proxy Authentication and for Cookie Authentication. - [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 - Note - This setting affects both the clustered-port (5984 by default) and the node-local port (5986 by default). 
 - 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_token = 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