Writing_Custom_Authentication_Plugins

Writing a Custom Authentication Plugin for Xataface

Xataface has a pluggable authentication framework that allows you to easily write your own custom authentication modules to tie in with other systems. Several plugins have already been created including:

• Yale CAS?
• LDAP?
• Facebook?
• HTTP?

Example: Creating a custom authentication plugin

Before we begin, a couple of conventions:

1. %XATAFACE_ROOT% refers to your Xataface installation directory. This is where all of the Xataface files are located includeing dataface-public-api.php
2. %SITE_ROOT% refers to your Xataface application's installation directory. This is where your conf.ini file, index.php, and other application files are stored.

About our plugin

Our plugin will be the simplest, most useless authentication plugin you can imagine. It simply checks an array of usernames and passwords to see if the password that the user supplied is valid.

Creating our plugin

1. Create the %XATAFACE_ROOT%/modules/Auth directory if it doesn't exist already. This directory will store all of our Xataface authentication plugins.
2. Create the %XATAFACE_ROOT%/modules/Auth/XDB directory if it doesn't exist already. This directory will house all of the scripts and files associated with our custom plugin.
3. Create a new PHP file named XDB.php inside our XDB directory that we just created, with the following contents:

   class dataface_modules_XDB {
       var $passwords = array(
           'steve' => 'stevespass',
           'mike' => 'foo'
       );
       function checkCredentials(){
           $auth =& Dataface_AuthenticationTool::getInstance();
           $creds = $auth->getCredentials();
           if ( @$this->passwords[$creds['UserName']] == $creds['Password'] ){
               return true;
           } else {
               return false;
           }
       }
   }

4. Now, change the [_auth] section of the conf.ini file to let Xataface know that we want to use our custom module:

   [_auth]
       auth_type=XDB

5. Try to log into your application. You'll notice that the only username/password combinations that are accepted are the ones that we specified in our $passwords array in our module.

This is just a simple example, but you can see how this can be expanded to provide more complex modules.

checkCredentials() not enough?

Some authentication plugins will need more control than simply checking credentials. Some plugins may want to make use if their own login forms, or redirect to other sites to handle the authentication. Xataface's authentication tool is up to the task, as virtually all parts of the login/logout process can be overridden and customized in your module. The previous example shows how the getCredentials() method can be overridden, but there are other methods that can be implemented to customize the login process as well.

e.g.

• showLoginPrompt() - This method is called when it is time to display the login prompt for the user. It could also be made to redirect to another site that has a login prompt.
• logout() - This is called when the user tries to log out. If there are any special cookies of variables that need to be cleaned up to facilitate a successful logout, you could implement this method.
• getLoggedInUser()
• getLoggedInUsername()
• getCredentials() - Handles the obtaining of credentials from the request or from the environment.
• authenticate() - Handles the whole login process

See Also:

• Application Delegate Class for before/after login/logout triggers that may be more appropriate in some circumstances than creating a custom authentication plugin.
• Xataface Authentication