Introduction to CouchDB with .NET part 21: starting with security

Introduction

In the previous post we looked at Mango operators related to arrays. With array operators such as $elemMatch, $in or $size we can write search terms related to elements in an array. Examples include searching for documents where an array field, such as “grades” includes at least one “A” or includes exactly two grades, not more or less. We’ve also seen how to dig deep into the object structure to query on elements that lie deep in the object graph, such as the price of a product of an order of a customer.

In this post we leave querying behind and start looking into some security aspects of CouchDB.

An important source that describes CouchDB security is this reference page. We’ll look at most of it in this series.

The Admin Party

A peculiar feature of CouchDB security is that by default all users are authorised to perform any action in the database: create databases, delete documents, perform replication, you name it. If your CouchDB Fauxton – or Futon for older versions – UI is available on an intranet page within your company then all users within the company intranet will have access to the database. All users are anonymous so there’s not even any useful logging that shows who did what in the database.

This is called an Admin Party in CouchDB. Click on the Admin Party link in the Fauxton UI:

This leads to a page where Server Administrators can be created. Server admins will have access to all databases, documents etc., i.e. everything we’ve done so far. Server administrators are not to be confused with DB administrators whose rights are typically constrained to one or more specific databases. We’ll look at DB admins later on as well.

The Create Admin page also shows some useful description around CouchDB security:

• If end-users will be accessing this CouchDB, you must create an admin account to prevent accidental (or malicious) data loss.
• Server admins can create and destroy databases, install and update _design documents, run the test suite, and edit all aspects of CouchDB configuration.
• Non-admin users have read and write access to all databases, which are controlled by validation functions. CouchDB can be configured to block all access to anonymous users.

We’ll see the various user types and control mechanisms in CouchDB throughout the posts on security.

Let’s just first create a server administrator. Enter a username and password of your choice, such as “admin” and “passw0rd”. The admin user has been instantly logged in:

We’re now logged in as a server administrator. We can always change our own password or create other server admins if we’re logged on as a server administrator:

Now log out from CouchDB using the Logout link highlighted above. You’ll then immediately be prompted to log on:

Try to perform any action on the screen without logging in, it should fail. You’ll either be redirected to the login page or notified with an angry red message like here:

So where are these server admin users stored? We know that there’s a database called _users. Log back in as the admin user and click on the _users database to see what it contains. No luck there, it only has a validation design document that’s triggered when a new user is entered.

Server admins are instead stored in the local CouchDB configuration file. If you recall then there are two configuration files in the etc folder of the CouchDB installation root: default.ini and local.ini. The server admin user will be added to local.ini with its password hashed in the admins section. Here’s what the admin user I created above looks like in the file:

[admins]
admin = -pbkdf2-4237bbdfa8bfb27723a059168078f02b2905aada,3b5b6b6b6d9a703e538a92245b239a0b,10

All “normal”, i.e. non-server-admin users will be added to the _users database. We’ll create one such user in the next section. Note that the _users database is a so-called system database and only server admins have access to system databases. System database names typically start with an underscore _. Normal, i.e. non-system databases are called user databases. We’ll see an important distinction between them soon.

Creating a new user

Database administrators will have extensive rights to a database. Only server admins can create new users and then they can be turned into database administrators or database members. We’ll see later on what a database member is.

Log in as admin to the Fauxton UI and select the _users database. Add a new document with the following structure:

{
  "_id": "org.couchdb.user:peter",
  "name": "peter",
  "password": "secret",
  "roles": [],
  "type": "user"
}

• _id: this is the same ID field that we’ve seen many times before but this particular ID is somewhat peculiar. A document in the _users database must have an ID with the org.couchdb.user prefix,
  followed by a colon and then some name. The reason for this constraint is namespacing in CouchDB. All users must belong to the org.couchdb.user namespace and it currently cannot be changed, i.e. we cannot assign our own namespace.
• name and password: the login name and password
• roles: users can be added to roles and this array will contain the names of roles that the user belongs to. We’ll ignore this for the time being, we’ll come back to roles in a later post.
• type: the document type which can only be “user” at the moment

Save the document and then open it again the Fauxton editor. You’ll see that the document was transformed. The most significant change is related to password hashing. It’s good that CouchDB takes care of the hashing with a salt for us. Therefore the password is not stored in plain text. Here’s the transformed document in my case:

{
  "_id": "org.couchdb.user:peter",
  "_rev": "1-07ab04081cc7dede84cbaea8edf15a11",
  "name": "peter",
  "roles": [],
  "type": "user",
  "password_scheme": "pbkdf2",
  "iterations": 10,
  "derived_key": "ff06a8a65fc89822d3e429c31cdd04fbd338cbc4",
  "salt": "dd553faeff71fc5d6ec56b542b45905a"
}

The update design document mentioned above is responsible for this conversion.

Now log out and log in again with this new user. Let’s see what Peter can do. Go ahead and test the various functions in the UI while logged in as Peter.

• Peter won’t have access to the system databases. Try to view and create a new user in the _users database, it will fail.
• All server admin activities such as setup, tasks, configuration, replication, server admin creation etc. will be either disabled or will redirect to the login page.
• Peter won’t be able to create a new database or delete an existing one.
• He will still be able to view all user databases, read their documents and insert new documents

The restrictions are good but the default user can still manipulate the documents in the user databases. We’ll remedy that in the next section.

For the next section create a new user called Mary the same way as above:

{
  "_id": "org.couchdb.user:mary",
  "name": "mary",
  "password": "secret",
  "roles": [],
  "type": "user"
}

Database administrators

We can allow Peter to concentrate on a database by making him a DB administrator. It’s similar to a server admin but for a single user database. Log out and log in as the server admin user. We have created a number of databases during this series. Pick one, or create a new database to test with, as you wish, for the next demo. I’ll select the “zipcodes” database by clicking on it in the Fauxton UI. Next click the Permissions menu point for the selected database:

Here we see two sections: admins and members. Within each section we have users and roles. We’ll concentrate on Admin users, i.e. database administrators. The UI shows the reason why the default Peter user has been able to access the user databases so easily:

“Database members can access the database. If no members are defined, the database is public.”

In the users text box add Peter:

Now log in as peter and try to modify the security settings of another database, such as “children”, by adding Mary as a DB admin. It will fail with an error message:

However, Peter can add Mary as a DB admin for the zipcodes database:

Peter and Mary are still not allowed to perform server admin activities like configuration changes but they are given admin functions on a specific database. They are administrators of the zipcodes database, nothing else.

Also note that Peter and Mary are not authorised to delete the zipcodes database even though they are admins:

Read the next part here.

You can view all posts related to data storage on this blog here.