Pluggable Authentication Tutorial

Limits: This tutorial only explains how to implement an Unmanaged Authentication plugin. Implementing a Managed Authentication plugin may be explained in a later version or another tutorial

This tutorial will explain how to write the authentication plugin, the location and installation of the plugin will be explained at the end. This is only required if you need to add an additional authentication mode to those already provided. See the AuthenticationPlugins page for more details on the available plugins.

Step 1: Name your plugin

Decide what your plugin will be called, and what it's unique id will be, a good idea would be for a popular general authentication system would be a single lowercase name, like yahoo. For a corporate or special authentication system, mycorp_auth_foo.

We'll be using "mycorp_auth_foo" as the id, and "My Corp Auth Foo" as the name, and MyCorpAuthFoo, as the class name

Step 2: Extend BaseAuth


<?php
class MyCorpAuthFoo extends BaseAuth {

        function MyCorpAuthFoo() {
                parent::BaseAuth('mycorp_auth_foo');
        }

The parent::BaseAuth('mycorp_auth_foo'); loads all registered setting into a field called mConfig.


<?php
 $this->mConfig
?>

To actually preform the user validation we have to have a function called validate


<?php
    function validate($user,$pass,$challenge,$response) {
        parent::validate($user,$pass,$challenge,$response);
        if (proprietary_authorize( $user, $pass , $this->mConfig['mycorp_auth_foo_server'], $this->mConfig['users_mycorp_auth_foo_ssl'] )) {
            $this->mErrors['login']=proprietary_getError();
                        $ret=USER_NOT_FOUND;
        } else {
            $ret=USER_VALID;
            $propUserInfo = proprietary_getUserInfo( $user );
            $this->mInfo["real_name"] = $propUserInfo['real_name'];
            $this->mInfo["email"] = $propUserInfo['email'] ;
            if ( !empty($propUserInfo['create_date']) ) {
                $this->mInfo['registration_date'] = strtotime( $propUserInfo['create_date'] );
            }
        }
        return $ret;
    }
?>

That's the authentication done. When implementing this it's worth noting that Bitweaver requires an email address and login name, and requires both to be unique, so if your authentication method doesn't provide an email address it might be worth looking at the existing imap auth plugin to see how it handles that case.

The plugin system preforms some checks before loading plugin so we have to provide some functions to answer it's questions.

The isSupported function checks to make sure that the auth plugin will work on the current server, a simple implementation could be to return true, in this case we will check to make sure the function proprietary_authorize exists


<?php
    function isSupported() {
                $ret = true;
                if (!function_exists('proprietary_authorize')) {
                        $this->mErrors['support']=tra("My Corp Auth Foo is not supported as the proprietary_authorize function doesn't exist.");
                        $ret = false;
                }
                return $ret;
        }
?>

Step 3: Override the error messages

This should be come unnecessary with a future version and this section will be removed


<?php
    function createUser(&$userattr) {
        $this->mErrors['create']=tra("Cannot create users for My Corp Auth Foo.");
        return false;
    }

    function canManageAuth() {
        $this->mErrors[]=tra("Cannot create users in for My Corp Auth Foo.");
        return false;
    }
?>

For those interested in Managed Authentication you would return true from the function canManageAuth and not set any error messages

Step 4: Permit the auth plugin to have settings <optional>


<?php
    function getSettings() {
        return array(
        'users_mycorp_auth_foo_server' => array(
            'label' => "My Corp Auth Foo Server",
            'type' => "text",
            'note' => "",
            'default' => '',
        ),
        'users_mycorp_auth_foo_ssl' => array(
            'label' => "Connect Using SSL",
            'type' => "checkbox",
            'note' => "",
            'default' => 'y',
        ),
    );
?>

This method returns an array of settings to be parsed by the plugin handler, it is worth noting that it recommended to start the setting name with users_, as the first part of the setting name will be removed to give the mConfig index. i.e. the value of setting users_mycorp_auth_foo_server is available in $this->mConfigmycorp_auth_foo_server>'mycorp_auth_foo_server';

And finally remember closing


<?php
?>
?>

Step 4: Using the plugin

There are two methods,

Place in the plugin scan directory (follow steps A)
Create a custom package and register the plugin in bit_setup_inc.php (follow steps B)

Step A: Plugin Scan Directory

Step 1: make the directories

Create the directory mycorp_auth_foo in users/auth.
This is used by the Plugin scanner to generate the unique id of your plugin.

Step 2: name the file

Save the newly created file as auth.php in that directory and your done.

`It will however name your plugin now MYCORP_AUTH_FOO Auth`

Step B: Custom Package

Step 1: Create your custom package

All wee need from that tutorial are steps 1 and 4 (a directory and a bit_setup_inc.php - tables are not required). Assume we make a package called mycorp_auth_foo. Your foocore/bit_setup_inc.php should look something like:


<?php
global $gBitSystem, $gBitSmarty;
$registerHash = array(
    'package_name' => 'mycorp_auth_foo',
    'package_path' => dirname( __FILE__ ).'/',
);
$gBitSystem->registerPackage( $registerHash );

Step 2: edit bit_setup_inc.php

Save the newly created file as plugin_auth.php in the new package directory.

Since is good practise to check to see if your package is active before changing settings, we will do that.


<?php
if( $gBitSystem->isPackageActive( 'mycorp_auth_foo' ) ) {
    BaseAuth::register('mycorp_auth_foo',array(
        'name' => 'My Corp Auth Foo',
        'file' => MYCORP_AUTH_FOO_PKG_PATH.'plugin_auth.php',
        'class' => 'MyCorpAuthFoo',
     ));
}
?>

</optional>