History of Pluggable Authentication Tutorial

^__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

{code source="php"}
<?php
class MyCorpAuthFoo extends BaseAuth {

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

{/code}

The parent::BaseAuth('mycorp_auth_foo'); loads all registered setting into a field called mConfig.
{code source="php"} $this->mConfig {/code}

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

{code source="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;
}
{/code}

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
{code source="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;
}
{/code}

!Step 3: Override the error messages

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

{code source="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;
}
{/code}

^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>

{code source="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',
),
);
{/code}

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->mConfig['mycorp_auth_foo_server'];

And finally remember closing

{code source="php"}
?>
{/code}

!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 ((Tutorial_Custom_Package|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:

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

{/code}

!!! 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.

{code source="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',
));
}
{/code}