Permalink
Switch branches/tags
Find file
Fetching contributors…
Cannot retrieve contributors at this time
804 lines (583 sloc) 25.5 KB

This section give details about the CouchAdmin object.

##Table of content

##Please read this first !!

The CouchAdmin class is only needed to manage users of a CouchDB server : add users, add admins, ...

You don't need the couchAdmin class to connect to CouchDB with a login / password. You only need to add your login and password to the DSN argument when creating your CouchDB client :

$client = new CouchClient ("http://theuser:secretpass@couch.server.com:5984","mydatabase");

##Managing CouchDB users

CouchDB rights management is really complex. This page can really help to understand how security is implemented in couchDB.

The CouchAdmin class contains helpful methods to create admins, users, and associate users to databases.

##Synopsys

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
// Here my couchDB is in "admin party" mode (no user, no admin defined)
//
// I create an "anonymous" connector to the database
$client = new CouchClient ("http://localhost:5984/","mydb" );
// I then create an instance of the couchAdmin class, passing the couchClient as a parameter
$anonymous_adm = new CouchAdmin($client);

// I create the first admin user
try {
    $anonymous_adm->createAdmin("superAdmin","secretpass");
} catch ( Exception $e ) {
    die("unable to create admin user: ".$e->getMessage());
}

//
// now my database is not in "admin party" anymore : to continue Administration I need to setup an authenticated connector
//
$admclient = new CouchClient ("http://superAdmin:secretpass@localhost:5984/", "mydb" );
$adm = new CouchAdmin($admclient);

// create a regular (no superadmin) user)
try {
    $adm->createUser("joe","secret");
} catch ( Exception $e ) {
    die("unable to create regular user: ".$e->getMessage());
}

// set "joe" as admin of the database "mydb"
try {
    $adm->addDatabaseAdminUser("joe");
} catch ( Exception $e ) {
    die("unable to add joe to the admins list of mydb: ".$e->getMessage());
}

// Oh no I missed up remove "joe" from database "mydb" admins
try {
    $adm->removeDatabaseAdminUser("joe");
} catch ( Exception $e ) {
    die("unable to remove joe from the admins list of mydb: ".$e->getMessage());
}

// and add it to the readers group of database "mydb"
try {
    $adm->addDatabaseReaderUser("joe");
} catch ( Exception $e ) {
    die("unable to add joe to the readers list of mydb: ".$e->getMessage());
}

// well... get the list of users belonging to the "readers" group of "mydb"
$users = $adm->getDatabaseReaderUsers();  // array ( "joe" )

##Getting started

__construct(CouchClient $client,$options = array()) The couchAdmin class constructor takes 2 parameters : a couchClient object and an array of configuration options.

$client : You have to be careful, the couchClient object should have enough credentials to perform the administrative tasks.

$options: This array has 2 possibles keys for the moments.

  • users_database : The user database to use (overwrite the default _users)
  • node : The node to use for the configuration. If it's not defined, the first node of the cluster_nodes will be taken.

Example :

// create a CouchClient instance
$client = new CouchClient("http://localhost:5984/","mydb");
// now create the CouchAdmin instance
$adm = new CouchAdmin($client);
// here $adm will connect to CouchDB without any credentials : that will only work if there is no administrator created yet on the server.

##Admin party

On a fresh install, CouchDB is in admin party mode : that means any operation (create / delete databases, store documents and design documents) can be performed without any authentication.

Below is an example to configure the first server administrator, that we will name couchAdmin with the password secretpass :

// create an anonymous couchClient connection (no user/pass)
$client = new CouchClient("http://localhost:5984/","mydb");
// now create the couchAdmin instance
$adm = new CouchAdmin($client);
//create the server administrator
try {
    $adm->createAdmin("couchAdmin","secretpass");
} catch ( Exception $e ) {
    die ("Can't create server administrator : ".$e->getMessage());
}

Now that the couch server got a server administrator, it's not in "admin party" mode anymore : we can't create a second server administrator using the same, anonymous couchClient instance. We need to create a couchClient instance with the credentials of couchAdmin.

// create a server administrator couchClient connection
$client = new CouchClient("http://couchAdmin:secretpass@localhost:5984/","mydb");
// now create the CouchAdmin instance
$adm = new CouchAdmin($client);

##Create users and admins

###createAdmin($login, $password, $roles = array())

The method createAdmin ($login, $password, $roles = array()) creates a CouchDB server administrator. A server administrator can do everything on a CouchDB server.

Example :

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

// Create an admin user
try {
    $adm->createAdmin("superAdmin","ommfgwtf");
} catch ( Exception $e ) {
    die("unable to create admin user: ".$e->getMessage());
}

###createUser($login, $password, $roles = array())

The method createUser($login, $password, $roles = array()) creates a CouchDB user and returns it.

Example :

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

// Create a user
try {
    $adm->createUser("joe","dalton");
} catch ( Exception $e ) {
    die("unable to create user: ".$e->getMessage());
}

Example - creating a user and adding it to some roles

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

$roles = array ("thief","jailbreaker");

try {
    $adm->createUser("jack","dalton",$roles);
} catch ( Exception $e ) {
    die("unable to create user: ".$e->getMessage());
}

###getUser($login)

The method getUser($login) returns the user document stored in the users database of the CouchDB server.

Example :

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

// get a user
try {
    $joe = $adm->getUser("joe");
} catch ( Exception $e ) {
    if ( $e->getCode() == 404 ) {
        echo "User joe does not exist.";
    } else {
        die("unable to get user: ".$e->getMessage());
    }
}

###getAllUsers()

The method getAllUsers() returns the list of all users registered in the users database of the CouchDB server. This method calls a view, so you can use the view query options !

Example :

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

// get all users
try {
    $all = $adm->getAllUsers();
} catch ( Exception $e ) {
    die("unable to get users: ".$e->getMessage());
}
print_r($all);

/** will print something like 
Array (
    stdClass (
        "id" => "_design/_auth",
        "key" => "_design/_auth",
        "value" => stdClass (
                        "rev" => "1-54a591939c91922a35efee07eb2c3a72"
                  )
    ),
    stdClass (
        "id" => "org.couchdb.user:jack",
        "key" => "org.couchdb.user:jack",
        "value" => stdClass (
                         "rev" => "1-3e4dd4a7c5a9d422f8379f059fcfce98"
                   )
    ),
    stdClass (
        "id" => "org.couchdb.user:joe",
        "key" => "org.couchdb.user:joe",
        "value" => stdClass (
                         "rev" => "1-9456a56f060799567ec4560fccf34534"
                   )
    )
)
**/

Example - including user documents and not showing the design documents

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $all = $adm->include_docs(true)->startkey("org.couchdb.user:")->getAllUsers();
} catch ( Exception $e ) {
    die("unable to get users: ".$e->getMessage());
}
print_r($all);

/** will print something like 
Array (
    stdClass (
        "id" => "org.couchdb.user:jack",
        "key" => "org.couchdb.user:jack",
        "value" => stdClass (
                         "rev" => "1-3e4dd4a7c5a9d422f8379f059fcfce98"
                   ),
        "doc" => stdClass ( "_id" => "org.couchdb.user:jack", ... )
    ),
    stdClass (
        "id" => "org.couchdb.user:joe",
        "key" => "org.couchdb.user:joe",
        "value" => stdClass (
                         "rev" => "1-9456a56f060799567ec4560fccf34534"
                   ),
        "doc" => stdClass ( "_id" => "org.couchdb.user:joe", ... )
    )
)
**/

##Removing users

Warning : this only works with CouchDB starting at version 1.0.1

###deleteAdmin($login)

The method deleteAdmin($login) permanently removes the admin $login.

Example : creating and immediately removing a server administrator

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

$adminLogin = "butterfly";
$adminPass = "wing";
try {
    $ok = $adm->createAdmin($adminLogin, $adminPass);
} catch (Exception $e) {
    die("unable to create admin user: ".$e->getMessage());
}
// here "butterfly" admin exists and can login to couchDB to manage the server

// now we remove it
try {
    $ok = $adm->deleteAdmin($adminLogin);
} catch (Exception $e) {
    die("unable to delete admin user: ".$e->getMessage());
}
// here "butterfly" admin does not exist anymore

Note : the response of deleteAdmin() method is a string : it's the hash of the password this admin had before been removed. Example : -hashed-0c796d26c439bec7445663c2c2a18933858a8fbb,f3ada55b560c7ca77e5a5cdf61d40e1a

###deleteUser($login)

The method deleteUser($login) permanently removes the user $login.

Example : removing a server user

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new couchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new couchAdmin($client);

try {
    $ok = $adm->deleteUser("joe");
} catch (Exception $e) {
    die("unable to delete user: ".$e->getMessage());
}
print_r($ok);

/** will print something like :
stdClass Object
(
    [ok] => 1
    [id] => org.couchdb.user:joe
    [rev] => 6-415784680cff486e2d0144ed39da2431
)
*/

##Roles assignation

###addRoleToUser($user, $role)

The method addRoleToUser($user, $role) adds the role $role to the list of roles user $user belongs to. $user can be a PHP stdClass representing a CouchDB user object (as returned by getUser() method), or a user login.

Example : adding the role cowboy to user joe

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->addRoleToUser("joe","cowboy");
} catch ( Exception $e ) {
    die("unable to add a role to user: ".$e->getMessage());
}
echo "Joe now got role cowboy";

###removeRoleFromUser($user, $role)

The method removeRoleFromUser($user, $role) removes the role $role from the list of roles user $user belongs to. $user can be a PHP stdClass representing a CouchDB user object (as returned by getUser() method), or a user login.

Example : removing the role cowboy of user joe

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->removeRoleFromUser("joe","cowboy");
} catch ( Exception $e ) {
    die("unable to remove a role of a user: ".$e->getMessage());
}
echo "Joe don't belongs to the cowboy role anymore";

##Database user security

CouchDB databases got two types of privileged users : the readers, that can read all documents, and only write normal (non-design) documents. The admins got all privileges of the readers, and they also can write design documents, use temporary views, add and remove readers and admins of the database. The CouchDB wiki gives all details regarding rights management.

###addDatabaseReaderUser($login)

The method addDatabaseReaderUser($login) adds a user in the readers list of the database.

Example - adding joe to the readers of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->addDatabaseReaderUser("joe");
} catch ( Exception $e ) {
    die("unable to add user: ".$e->getMessage());
}

###addDatabaseAdminUser($login)

The method addDatabaseAdminUser($login) adds a user in the admins list of the database.

Example - adding joe to the admins of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->addDatabaseAdminUser("joe");
} catch ( Exception $e ) {
    die("unable to add user: ".$e->getMessage());
}

###getDatabaseReaderUsers()

The method getDatabaseReaderUsers() returns the list of users belonging to the readers of the database.

Example - getting all users beeing readers of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $users = $adm->getDatabaseReaderUsers();
} catch ( Exception $e ) {
    die("unable to list users: ".$e->getMessage());
}
print_r($users);
// will echo something like: Array ( "joe" , "jack" )

###getDatabaseAdminUsers()

The method getDatabaseAdminUsers() returns the list of users belonging to the admins of the database.

Example - getting all users beeing admins of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $users = $adm->getDatabaseAdminUsers();
} catch ( Exception $e ) {
    die("unable to list users: ".$e->getMessage());
}
print_r($users);
// will echo something like: Array ( "william" )

###removeDatabaseReaderUser($login)

The method removeDatabaseReaderUser($login) removes a user from the readers list of the database.

Example - removing joe from the readers of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->removeDatabaseReaderUser("joe");
} catch ( Exception $e ) {
    die("unable to remove user: ".$e->getMessage());
}

###removeDatabaseAdminUser($login)

The method removeDatabaseAdminUser($login) removes a user from the admins list of the database.

Example - removing joe from the admins of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->removeDatabaseAdminUser("joe");
} catch ( Exception $e ) {
    die("unable to remove user: ".$e->getMessage());
}

##Database roles security

Just like users, roles can be assigned as admins or readers in a CouchDB database. The CouchDB wiki gives all details regarding rights management.

###addDatabaseReaderRole($role)

The method addDatabaseReaderrole($role) adds a role in the readers list of the database.

Example - adding cowboy to the readers of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->addDatabaseReaderRole("cowboy");
} catch ( Exception $e ) {
    die("unable to add role: ".$e->getMessage());
}

###addDatabaseAdminRole($role)

The method addDatabaseAdminRole($role) adds a role in the admins list of the database.

Example - adding cowboy role to the admins of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->addDatabaseAdminrole("cowboy");
} catch ( Exception $e ) {
    die("unable to add role: ".$e->getMessage());
}

###getDatabaseReaderRoles()

The method getDatabaseReaderRoles() returns the list of roles belonging to the readers of the database.

Example - getting all roles beeing readers of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $roles = $adm->getDatabaseReaderRoles();
} catch ( Exception $e ) {
    die("unable to list roles: ".$e->getMessage());
}
print_r($roles);
// will echo something like: Array ( "cowboy" , "indians" )

###getDatabaseAdminRoles()

The method getDatabaseAdminRoles() returns the list of roles belonging to the admins of the database.

Example - getting all roles beeing admins of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $roles = $adm->getDatabaseAdminRoles();
} catch ( Exception $e ) {
    die("unable to list roles: ".$e->getMessage());
}
print_r($roles);
// will echo something like: Array ( "martians" )

###removeDatabaseReaderRole($role)

The method removeDatabaseReaderRole($role) removes a role from the readers list of the database.

Example - removing cowboy from the readers of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->removeDatabaseReaderRole("cowboy");
} catch ( Exception $e ) {
    die("unable to remove role: ".$e->getMessage());
}

###removeDatabaseAdminRole($role)

The method removeDatabaseAdminRole($role) removes a role from the admins list of the database.

Example - removing martians from the admins of the database mydb

<?PHP

use PHPOnCouch\Couch, PHPOnCouch\CouchClient, PHPOnCouch\CouchAdmin; $client = new couchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" ); $adm = new CouchAdmin($client);

try {
    $adm->removeDatabaseAdminRole("martians");
} catch ( Exception $e ) {
    die("unable to remove role: ".$e->getMessage());
}

##Accessing Database security object

Each Couch database got a security object. The security object is made like :

{
    "admins" : {
        "names" : ["joe", "phil"],
        "roles" : ["boss"]
    },
    "readers" : {
        "names" : ["dave"],
        "roles" : ["producer", "consumer"]
    }
}

PHP on Couch provides methods to directly get and set the security object.

###getSecurity()

The method getSecurity() returns the security object of a CouchDB database.

Example - getting the security object of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new couchAdmin($client);

try {
    $security = $adm->getSecurity();
} catch ( Exception $e ) {
    die("unable to get security object: ".$e->getMessage());
}

###setSecurity($security)

The method setSecurity($security) set the security object of a Couch database

Example - setting the security object of the database mydb

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client);

try {
    $adm->setSecurity($security);
} catch ( Exception $e ) {
    die("unable to set security object: ".$e->getMessage());
}

##Database options

CouchDB got a special database used to store users. By default this database is called _users, but this can be changed.

###CouchAdmin users_database

To create a couchAdmin instance and specify the name of the users database, use the constructor second parameter $options, setting the option users_database:

Example - setting the couchdb users database name on couchAdmin object creation

<?PHP
use PHPOnCouch\Couch,
    PHPOnCouch\CouchClient,
    PHPOnCouch\CouchAdmin;
$client = new CouchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
$adm = new CouchAdmin($client, array ("users_database"=> "theUsers") );

###setUserDatabase($name)

The setUsersDatabase($name) method allows to specify an alternate name for the users database on an already created couchAdmin instance.

###getUserDatabase($name)

The getUsersDatabase($name) method return the name that is used actually to connect to the users database.