Authentication plugin development

Introduction

An authentication plugin has some additional requirements over a regular plugin. Here we list the requirements.

To make creating your own authentication plugin easier, you should extend the abstract AuthPluginBase class.

To get an idea of the possibilities, check out the three core authentication plugins (check their pages for more information about configuration options):

• Authdb Database authentication - this is the default method for all new LimeSurvey installations.info
• Authwebserver Webserver authentication - This one skips the login form, and provides methods for user creation. info
• AuthLDAP LDAP authentication - Adds a custom error message and relies on a user being present in the LimeSurvey database. info

The authentication method name

Every authentication plugin has a name. Usually, it is the same as the plugin name. Still, sometimes, it may be different from the plugin name, or it vary from language to language.

The method getAuthMethodName returns how the authenticantion method name should be displayed. It is used, for example, in the "authentication method" dropdown in the login form.

Please overwrite the method getAuthMethodName. This should return the authentication method name already translated in the current language being used.

Please see the Authdb plugin for an example.

The logins events

There are 6 primary events you can subscribe to:

beforeLogin

This is called first, and can possibly disable the loginform, for example when webserver authentication is used and we trust on that. To do this, use $this->setAuthPlugin()

newLoginForm

Here you can add your own elements to the form. You should add your username/password elements, but could also add a domain selector or anything else you need. This will only be shown when the selected authentication method was chosen on the selector that is added when more then one plugin is present. When your authentication plugin does not need a form, and can not be selected as an option (like webserver authentication) you should not add a form element here.

$this->getEvent()                  // Get the current event
     ->getContent($this)           // Get the content for this plugin
     ->addContent(CHtml::tag(      // And add some content to it
         'li', 
         array(), 
         "<label for='user'>"  . gT("Username") . "</label><input name='user' id='user' type='text' size='40' maxlength='40' value='' />"))
     ->addContent(CHtml::tag(
         'li', 
         array(), 
         "<label for='password'>"  . gT("Password") . "</label><input name='password' id='password' type='password' size='40' maxlength='40' value='' />"));

afterLoginFormSubmit

When the form for this plugin was submitted, this event is called. Here you can handle setting the values to the plugin. This event is also called when there was no form submitted and form display was canceled in the beforeLogin event.

remoteControlLogin

This replace the default login submit to set the value from get_session_key function.

The plugin receive : identity, plugin, username and password. Default functionnality set username and password to the identity. If Auth Plugin use username password to authenticate, you just have to register to the event.

For LimeSurvey Core plugin : only AuthDB and AuthLDAP can be used to authenticate via remote control.

newUserSession

This is where the real authentication takes place. You should use $this->setAuthSuccess($oUser) for a successful attempt and provide a User object. If you fail to do so it will result in an authentication failure. If you need to provide a message about why the authentication failed, you can do so by using $this->setAuthFailure($code, $message) where code is any code other than 0. The code is not used at this moment. The message should be a message in English, localised using the available tools in the plugin api. See the general plugin documenation for more information about that topic.

beforeLogout

This is fired before the user is destroyed and the session regenerated. This is the time for cleanup / logout in external systems if needed.

afterLogout

When the user is destroyed, you might want to redirect to a different page then currently defined. This is the right place to do so.

Other events to use

getGlobalBasePermissions

Used to append the Authentification Permission line. See getGlobalBasePermissions with the example of AuthWebserver.

beforeHasPermission

To give specific events for some user, used in AuthLdap, see beforeHasPermission.

afterFailedLoginAttempt

This event is fired during authentification, you don't need action on this event.