History of Pluggable Authentication Tutorial
Version 1 | Current version | |
---|---|---|
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 pluginDecide 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
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
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
Step 3: Override the error messagesThis should be come unnecessary with a future version and this section will be removed
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>
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 pluginThere are two methods,
Step A: Plugin Scan DirectoryStep 1: make the directoriesCreate 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 fileSave 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 PackageStep 1: Create your custom packageAll 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:
Step 2: edit bit_setup_inc.phpSave 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.
| 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 pluginDecide 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
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
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
Step 3: Override the error messagesThis should be come unnecessary with a future version and this section will be removed
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>
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 pluginThere are two methods,
Step A: Plugin Scan DirectoryStep 1: make the directoriesCreate 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 fileSave 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 PackageStep 1: Create your custom packageAll 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:
Step 2: edit bit_setup_inc.phpSave 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.
|