User Account and Database Provisioning for CouchDB

Many developers choose to store user-specific data in CouchDB by creating a separate database for each user. This approach can provide better security and performance than storing all user data in a single, monolithic database. The main obstacle to setting up per-user databases, however, is the lack of a built-in method for provisioning user accounts and dbs and setting up security so a user's database is private. This repo contains a CouchDB OS daemon that can be used to provision per-user databases for most use cases.

How it works

A client app makes an HTTP request to the provisioning daemon with a desired username and password. The daemon performs the following steps and returns information about the created user and database.

1. Generates a unique database name based on the username and (optionally) a configurable namespace string.
2. Adds a document to the _users database for the new user containing the database name as a custom property.
3. Sets the _security document for the new database so the user can administrate their db.
4. Adds a validate document update function that restricts document updates to the database owner.
5. Returns a JSON document containing the new user's entry in the _users database (minus the password) and the generated database name.

Requirements

• Apache CouchDB 1.4 or later
• node 0.10 or later plus npm
• shell access to your CouchDB server

Installation

1. git clone https://github.com/pegli/couchdb-dbperuser-provisioning.git
2. cd couchdb-peruser-provisioning
3. npm install -g

Configuration

The provisioning OS daemon uses CouchDB's configuration system. The easiest way to set up the daemon is to create an ini file in /etc/couchdb/local.d with the following contents:

[myapp_provisioning_config]
admin_username = admin
admin_password = admin
namespace = com.example.myapp
add_namespace_to_dbname = true
db_name_format = ns_user
port = 8100

[os_daemons]
; Linux
myapp_provision_daemon = /usr/bin/node /usr/bin/couchdb-provision myapp_provisioning_config
; Windows
; myapp_provision_daemon = "C:\Program Files (x86)\nodejs\node.exe" C:\Users\[USER_NAME]\AppData\Roaming\npm\node_modules\couchdb-provision\lib\provision.js myapp_provisioning_config

[httpd_global_handlers]
_myapp_provision = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:8100">>}

When the daemon starts up, it will query CouchDB for the configuration section provided as the first argument after the script name in the os_daemons section. You may need to change the path to the node executable and the couchdb-provision script depending on your system settings (for example, on OSX, the paths are under /usr/local/bin).

Reference

admin_username (string) - the name of the admin user to use to create new databases and users.

admin_password (string) - the password of the admin user.

port - (number) - the port on which to start the configuration daemon.

namespace (string) - a key that represents the application for which the user is being provisioned. Application-specific data, including the user's generated database name, will be stored in the user document under this key.

add_namespace_to_dbname (boolean) - if true, generated database names will include the namespace string.

db_name_format (string) - Format for the database name if add_namespace_to_dbname is true. Options: ns_user = namespace then username, user_ns = username then namespace

References

• the CouchDB Security Overview
• Matt Woodward's Blog: The Definitive Guide to CouchDB Authentication and Security (somewhat outdated but helpful in explaining the various security models)