3.5. Authentication and Authorization — Apache CouchDB 2.0 Documentation

### Navigation

- API Reference
- Config Reference |
- next |
- previous |
- Apache CouchDB 2.0 Documentation »
- 3. Configuring CouchDB »

# 3.5. Authentication and Authorization

## 3.5.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.5.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 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

  `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.5.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.5.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

### Navigation

- API Reference
- Config Reference |
- next |
- previous |
- Apache CouchDB 2.0 Documentation »
- 3. Configuring CouchDB »