Developing authentication providers

From KnowledgeTree Community

Authentication providers are different ways of authenticating a user in the system. An authentication source is a particular instance of an authentication provider, fully configured.

Authentication providers generally extend the KTAuthenticationProvider class:

require_once(KT_LIB_DIR . '/authentication/authenticationprovider.inc.php');

class KTLDAPAuthenticationProvider extends KTAuthenticationProvider {
    ...
}

Authentication providers are registered with the plugin they come with:

$oPlugin->registerAuthenticationProvider('LDAP Authentication', 'KTLDAPAuthenticationProvider', 'ktstandard.authentication.ldapprovider', 'ldap/ldapauthenticationprovider.inc.php');

• The first parameter is the display name of the authentication provider.
• The second parameter is the name of the class which describes the authentication provider's behaviour
• The third parameter is the unique namespaced name of the authentication provider
• The fourth parameter is the path to the implementation of the authentication provider (ie, the file in which the class in the second parameter is defined)

Authentication providers need to set their name and namespace within their class too:

class KTLDAPAuthenticationProvider extends KTAuthenticationProvider {
    var $sName = "LDAP authentication provider";
    var $sNamespace = "ktstandard.authentication.ldapprovider";
    ...
}

Authentication providers are only required to provide a getAuthenticator method, This must return a fully-configured authenticator object for the given source:

    function &getAuthenticator($oSource) {
        return new LDAPAuthenticator($oSource);
    }

An authenticator needs to implement the following method:

    function checkPassword($oUser, $sPassword) {
        ...
    }

The authenticator can optionally implement a method to call when the user explicitly logs out:

    function logout($oUser) {
        ...
    }

The authentication provider can optionally provide the ability to display and configure an authentication source (for example, to get an LDAP server's address and base DN). The showSource method can output HTML to place when describing the source:

    function showSource($oSource) {
        ...
    }

The do_editSourceProvider function will be called when an administrator wishes to edit the configuration of an authentication source. This is generally a form to fill in. Should the provider wish to have multiple pages for configuration, it should set the action request variable to editSourceProvider, and the request will be passed back to this function. It is up to the provider to determine which page of many it is on, or when the configuration can finally be saved.

    function do_editSourceProvider() {
        ...
    }

When it is finished (successfully or otherwise), it should perform a redirect to the viewsource action using successRedirectTo or errorRedirectTo:

    function do_editSourceProvider() {
        ...
        $this->successRedirectTo('viewsource', _("Configuration updated"), 'source_id=' . $oSource->getId());
    }

The provider can optionally provide the ability to add a user that already exists in the source. For example, adding an account from an existing LDAP directory. The provider must implement the do_addUserFromSource() method. Creating the user in the database is currently entirely the job of the provider, although this will change in future. Once the provider is finished with adding a user, it should perform a redirect to the main action using successRedirectToMain or errorRedirectToMain:

    function do_addUserFromSource() {
        ...
        $this->successRedirectToMain(_('Created new user') . ': ' . $oUser->getUsername());
    }

The provider can optionally provide the ability to display and additional details about a user that reside in the authentication provider's implementation. For example, it may display and allow the editing of the LDAP DN of the user, or of an email address that the authentication provider will use to authenticate the user against an IMAP server.

To display some details about the user, the provider needs to implement the showUserSource method, which should return a string to display in a provider-specific group of information about the user:

    function showUserSource($oUser, $oSource) {
        ...
    }

The do_editUserSource action method can be used to allow the administrator to edit the additional details about the user. This may return output to display on the page, and the action request variable may be set to editUserSource to return control back to the provider for multi-page configuration. Once the provider is finished saving the details, control must be returned to the editUser action on the dispatcher using successRedirectTo or errorRedirectTo.

    function do_editUserSource() {
        ...

        $this->successRedirectTo("editUser", _("Details updated"),
            sprintf('user_id=%d', $oUser->getId()));
    }