Using SugarCRM as an authentication system

Demo available : you can now directly test what’s explained in this article. A demo is available here.

SugarCRM configuration

We’ll use sugarcrm Contacts module as our application users repository. What we need on sugar side are just a couple of new custom fields: a password text field and a checkbox to enable/disable the user login on our system. Please note that saying “users” I refer to our custom application users, not sugar users. To be clearer, sugar users are those that can login into sugarcrm interface. Our users are what on sugarcrm are “contacts”.
After creating the new custom fields we need to add the checkbox in sugar Contacts EditView panel, to be able to effectively use it.
Obscure? Don’t worry, I’ve done a simple animation with wink, detailing all the process.You can watch it here
We are now ready on the sugar side. What SOAP are we going to use this time?
We’ve already seen (see previous article) how to query sugarcrm via SOAP, so we are already able to check if a user exists and is enabled, now we need to write to sugar(when a new user gets created). Our SOAP method is set_entry. Let’s see the new code to add to our SugarSoap class….

New methods in SugarSoap class
First we add a generic setEntry function that will be used for writing on various sugarcrm modules:

/**
*       Modify sugar entry with given data(used by other set### functions) 
*
**/             
function setEntry($module,$array){
        $data_array=array();
        while(list($name,$value)=each($array)){
                $data_array[]= array(
                        'name'  =>      $name,
                        'value' =>      $value  
                );
        }
        $result = $this->proxy->set_entry(
                $this->sess,
                $module,
                $data_array
        );
        return $result;
}

The set_entry method of sugar soap interface requires 3 parameters:

1. A valid sugar session id
2. The module name (i.e. Contacts)
3. The data array in sugar format(a name/value couple for each field)

In our setEntry method, we’re passing an associative array, so with the “while” loop we turn it into a sugarcrm accepted array. A note about set_entry : if an “id” field is passed within the data_array parameter, sugarcrm will do an update of the record with the given id, othewise it will be intended as an “insert”, and a new record will be created.
Now we can add “setXXX” methods very easily for the modules we’re interested in. In this case:

function setContact($array){
        return $this->setEntry("Contacts",$array);
}

The authentication class
What we need is a simple class to manage new user creation and authentication of existing users.
Here is a draft:

<?php
include_once "SugarSoap.php";
class UserManagement{
        var $soap;
        function UserManagement(){
                // here goes your sugar installation address
                $this->soap=new SugarSoap('http://mysugar/soap.php?wsdl');
        }               
        function authenticate($email,$password){
                $result=$this->soap->getContacts(" contacts_cstm.can_login_c='1' 
                                                and contacts.email1='".$email."' 
                                                and contacts_cstm.password_c='".$password."'",
                                                1,"");
                if($result['result_count']>0){
                        // Authenticated
                        // transform return values into an associative array
                        $result=$this->soap->nameValuePairToSimpleArray(
                                        $result['entry_list'][0]['name_value_list']);
                        /**
                        *       Here we can add code for managing the authenticated user, 
                        *       for example put some user data in a session variable
                        *       (id, first and last name, email etc.)
                        *       Something like this:
                        **/
                        $_SESSION['user_data']=$result;
                        return true;
                } else{ 
                        // Not authenticated
                        /**
                        *       and here we can add code for managing the authentication error, 
                        *       for example a notification email to someone     
                        **/
                        return false;
                }
        }
        
}
?>

Let’s focus on the method “authenticate”. This is obviously used to check the credentials for a user who’s trying to log in into our application. When calling the “getContacts” method, we check that the user is authorized(can_login=1), and that her/his email/password pair is correct. If someone matches, the result_count field will be greater than zero.

In an hypothetic user registration process we also need a “createUser” method” expecting at least an email and a password. Here it is :

function createUser($email,$password){
        return $this->soap->setContact(array(
                        "email1"        => $email,
                        "password_c"    => $password
        ));
}

Remember that the email field name in sugar “Contacts” module is “email1” and that password is the custom field “password_c” field we created.

A basic user registration page
At this point we have all the basics to manage a simple authentication process. A simple “register.php” page could be something like this:

<?php
/**
*       Trivial and incomplete example of
*       user registration. Missing are lots of
*       things, like password confirmation or 
*       checking that a user with the same email
*       is already registered on the system
*
**/
if(isset($_POST['submit'])){
        require_once "UserManagement.php";
        $usman=new UserManagement();
        $usman->createUser($_POST['email'],$_POST['password']);
        echo "User created";
        die();
}

?>
<html>
<body>
<form method=POST>
<table>
        <tr>
                <td>Email</td>
                <td><input type=text name=email></td>
        </tr>
        <tr>
                <td>Password</td>
                <td><input type=password name=password></td>
        </tr>
        <tr>
                <td colspan=2 align=center>
                        <input type=submit name=submit value="Register">
                </td>
        </tr>
</table>        
</form>
</body>
</html> 

The newly created user won’t be able to log in into the system because the custom field “can_login_c” defaults to 0. A sugar user has to check that field to enable user access to the application. In a complete process there will be notification emails, fields controls and other security related stuff.

A sample login page will be something like this:

<?php
/**
*       Similar notes as for the registration
*       page.
**/
if(isset($_POST['submit'])){
        require_once "UserManagement.php";
        $usman=new UserManagement();
        if($usman->authenticate($_POST['email'],$_POST['password'])){
                echo "User authenticated";
        }else {
                echo "Authentication error";            
        }
        die();
}

?>
<html>
<body>
<form method=POST>
<table>
        <tr>
                <td>Email</td>
                <td><input type=text name=email></td>
        </tr>
        <tr>
                <td>Password</td>
                <td><input type=password name=password></td>
        </tr>
        <tr>
                <td colspan=2 align=center>
                        <input type=submit name=submit value="Login">
                </td>
        </tr>
</table>        
</form>
</body>
</html> 

Should be quite self-explanatory.

From here it should be easy to build a robust, comfortable and easy to manage authentication system. As you’ve seen, the amount of code to be written is fairly low, as most of the job is demanded to sugar. There are a number of features we can add to make a more powerful system. Here are a few:

1. Encoded passwords(md5 or sha). This would ensure a higher level of security in case of db tampering, but will make password recovery impossible.
   You could prefer one method or the other depending on numerous factors.
2. A status field instead of a simple “can_login” checkbox, for example to have waiting for approval,enabled,blocked,revoked users.
   In this case you’d need to create a dropdown field in sugar.
3. A “group” field, to implement different privileges for different users

and so on. I hope that this overview is clear enough to allow anyone to tailor her/his own system easily.

Before closing the article
Just wanted to name another useful method of sugar soap interface. I’m talking about “get_module_fields”.
This is a simple method that accepts as parameters a session id and the module name and gives back a list of available fields for the given modules. This is quite useful while developing on sugar/soap. I’m not going to write here the code to use it because you already know how to do…..

Resources
Sugar CRM integration with custom PHP applications (I)
The first article of this series. There you will find the basis of what exposed in the current article.

Sugar CRM integration – website session and SOAP session
The third article of this series. It’s about how to use web/soap session ids  in SugarCRM.