Login   Register  
PHP Classes
elePHPant
Icontem

File: site/lib/DB/couch/doc/couch_admin.md

Recommend this page to a friend!
Stumble It! Stumble It! Bookmark in del.icio.us Bookmark in del.icio.us
  Classes of Muhammad Mengrani  >  PHP CouchDB Product CRUD  >  site/lib/DB/couch/doc/couch_admin.md  >  Download  
File: site/lib/DB/couch/doc/couch_admin.md
Role: Auxiliary data
Content type: text/plain
Description: Auxiliary data
Class: PHP CouchDB Product CRUD
Manage products stored in a CouchDB database
Author: By
Last change:
Date: 1 year ago
Size: 25,749 bytes
 

Contents

Class file image Download
This section give details about the couchAdmin object.

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](http://wiki.apache.org/couchdb/Security_Features_Overview) 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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    // 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" )
    

Creating a couchAdmin instance
==============================

The couchAdmin class constructor takes an only parameter : a couchClient object. You have to be careful, the couchClient object should have enough credentials to perform the administrative tasks.

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.


First time configuration of CouchDB
-----------------------------------

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);



Creating / getting users
========================

Creating a server administrator
-------------------------------

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

Example :

    <?PHP
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Creating a normal user
----------------------

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

Example :

    <?PHP
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Getting a user document
-----------------------

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

Example :

    <?PHP
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
        }
    }


Getting all users documents
---------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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

Removing a server administrator
-------------------------------

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

Example : creating and immediately removing a server administrator

    <?PHP
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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

Removing a user
---------------

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

Example : removing a server user

    <?PHP
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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
    )
    */



Assigning roles to users
========================

Assigning a role to a user
-----------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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";


Removing a role from the list of roles a user belongs to
--------------------------------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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";



Assigning users to databases
============================

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.](http://wiki.apache.org/couchdb/Security_Features_Overview)


Adding a user to the "readers"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Adding a user to the "admins"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Getting the list of "readers" of the database
---------------------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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" )


Getting the list of "admins" of the database
---------------------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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" )


Removing a user from the "readers"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Removing a user from the "admins"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }



Assigning roles to databases
============================

Just like users, roles can be assigned as admins or readers in a CouchDB database.
[The CouchDB wiki gives all details regarding rights management.](http://wiki.apache.org/couchdb/Security_Features_Overview)


Adding a role to the "readers"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Adding a role to the "admins"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Getting the list of "readers" of the database
---------------------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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" )


Getting the list of "admins" of the database
---------------------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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" )


Removing a role from the "readers"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Removing a role from the "admins"
------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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 the 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.


Getting the security object
---------------------------

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

Example - getting the security object of the database mydb

    <?PHP
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }


Setting the security object
---------------------------

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

Example - setting the security object of the database mydb

    <?PHP
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $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());
    }

Setting the name of the CouchDB users database
==============================================

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


Setting the users database name on couchAdmin creation
------------------------------------------------------

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
    require_once "lib/couch.php";
    require_once "lib/couchClient.php";
    require_once "lib/couchAdmin.php";
    $client = new couchClient ("http://couchAdmin:secretpass@localhost:5984/","mydb" );
    $adm = new couchAdmin($client, array ("users_database"=> "theUsers") );
    
Changing the users database name of an existing couchAdmin instance
-------------------------------------------------------------------

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

Getting the users database name currently set in an existing couchAdmin instance
--------------------------------------------------------------------------------

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