Cloudant Sync Security Configuration

Apache CouchDB http://couchdb.apache.org supports authentication and authorization functionalities which come in handy when setting up a production server or when you need to restrict (anonymous) users.

Cloudant also supports authentication https://github.com/cloudant/sync-android#authentication making it easier to connect and authorize opensrp-client application.

Below are the steps required to configure this security functionality: -

Create a new Admin user
- For example, creating a system admin with "rootuser" as the username and "adminpass" as the password.
```
> HOST="http://127.0.0.1:5984"

> curl -X PUT $HOST/_config/admins/rootuser -d '"adminpass"'
""
```
  System admin is not restricted in a CouchDB installation.

Confirm that the new system admin has been created successfully

Without credentials

> curl -X PUT $HOST/yourdatabase
{"error":"unauthorized","reason":"You are not a server admin."}

With credentials

> HOST="http://rootuser:adminpass@127.0.0.1:5984"
> curl -X PUT $HOST/yourdatabase
{"ok":true}

Create a new database user

For example, creating a user "test" with password "pass1"

curl -X PUT http://localhost:5984/_users/org.couchdb.user:test \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"name": "test", "password": "pass1", "roles": [], "type": "user"}'

NB: Passwords for existing databases can be changed.

Check where the new database user exists

Request

curl -X POST http://localhost:5984/_session -d 'name=test&password=pass1'

Correct Response
```
{"ok":true,"name":"test","roles":[]}
```

Assign the new user to your database (Authorization)
- This is done by creating authorization rules. These rules are set up by a server admin and can be modified at any time.
  For Example, assigning yourdatabase "test" admin and member privilege
```
> curl -X PUT http://localhost:5984/yourdatabase/_security \
     -u rootuser:adminpass \
     -H "Content-Type: application/json" \
     -d '{"admins": { "names": ["test"], "roles": [] }, "members": { "names": ["test"], "roles": [] } }'
```
  → If both the names and roles fields of either the admins or members properties are emptyarrays, it means the database has no admins or members.
  → Having no admins, onlyserver admins (with the reserved _admin role) are able to update design document and make other admin level changes.
  → Having no members, any user can write regular documents (any non-design document) and read documents from the database.
  → If there are any member names or roles defined for a database, then only authenticated users having a matching name or role are allowed to read documents from the database.
  → For complex scenarios, use roles i.e. update database users to have roles and assign these roles to your database.

Confirm that authorization rules have been updated

Request

curl -X GET -u test:pass1 http://localhost:5984/yourdatabase/_security

Correct Response

{"admins":{"names":["test"],"roles":[]},"members":{"names":["test"],"roles":[]}}

In opensrp-client update AllConstants.CloudantSync.class

public static class CloudantSync {
   ...
    public static final String COUCH_DATABASE_NAME = "yourdatabase";
    public static final String COUCH_DATABASE_USER = "test";
    public static final String COUCH_DATABASE_PASS = "pass1";
}

NB: Committing this file after adding your credentials will be a big security risk since the database can be accessed on the browser the the port is open.

Due to the above security changes, more changes are required in the server side to enable opensrp server app connect to couchdb as follows:
- Update couchdb.properties username/password with the right couchdb login credentials
- Update url value in couchdb-lucence/src/maina/java/resources/couchdb-lucene.ini to url = http://rootuser:adminpass@localhost:5984/ to enable couch-lucene to connect to couchdb and rebuild the project
Test your application

To restrict browser access, you can configure [couch_httpd_auth] with require_valid_user:true in couchdb local.ini file although this is not required.

References: