Version 1

Pluggable Authentication Tutorial

A brief overview of create a custom authentication plugin

Created by: Hash9, Last modification: 23 Jul 2006 (16:35 UTC) by Hash9
Draft: This tutorial is a draft and being written, it maybe in accurate or wrong or both.

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.

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

class MyCorpAuthFoo extends BaseAuth {

MyCorpAuthFoo() {

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


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

function validate($user,$pass,$challenge,$response) {
        if (
proprietary_authorize$user$pass $this->mConfig['mycorp_auth_foo_server'], $this->mConfig['users_mycorp_auth_foo_ssl'] )) {
        } else {
$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'] );

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

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;

Step 3: Override the error messages

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

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

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

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>

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


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:

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.

if( $gBitSystem->isPackageActive'mycorp_auth_foo' ) ) {
'name' => 'My Corp Auth Foo',
'file' => MYCORP_AUTH_FOO_PKG_PATH.'plugin_auth.php',
'class' => 'MyCorpAuthFoo',
Page History
17 Apr 2009 (06:36 UTC)
Add link to AuthenticationPlugins
Lester Caine81.138.11.1362
Current • Source
View • Compare • Difference • Source