Extension:BOINC Authentication

This plug-in provides automatic authentication to a wiki based on prior authentication to a co-located BOINC project. It is designed so that all authentication (and e-mail verification) is handled by BOINC, not the wiki. It is possible to assign users to various permission groups on the wiki based on their status on the BOINC project (eg. special user bits or credit).

BOINC
BOINC (the Berkeley Open Infrastructure for Network Computing) is a distributed computing infrastructure where volunteers "donate" the spare cycles on their personal or office computers (Windows, Mac, or Linux) to a distributed computing project, nominally whenever their screensaver is running. BOINC was originally created as the second generation of SETI@home, but was made general enough that other projects could use it simply by substituting their own compute thread code and graphics thread code into the general framework. BOINC has been used for projects such as Einstein@Home, ClimatePrediction.net, Folding@home, Rosetta@Home, etc. A more complete list of projects can be found from the BOINC website; the list of new projects is steadily growing.

In addition to managing the computations of a distributed cluster, each BOINC project has a web site which lists top scores for users and computers, facilitates participation in teams, and provides discussion forums so that users may communicate both amongst themselves and with the project developers and administrators. BOINC therefore provides an easy way for volunteers to participate in an on-line community related to the project.

This plug-in provides a way for a BOINC project to easily add a wiki, with authentication to the BOINC project providing automatic and transparent authentication to the wiki.

Installation and Configuration
Installation of both the MediaWiki software and this extension are both straightforward. To make the extension work seamlessly you will need to edit one file in the MediaWiki source code to add an invocation of a "hook" function to intercept the wiki login page and redirect it to the BOINC project's login page (see below).

This extension has been most recently tested with MediaWiki 1.13. It (or an earlier version) was previously tested with 1.10.3 and 1.8.2.

Install BOINCAuthPlugin.php
Instructions for getting the file BOINCAuthPlugin.php are given below. Simply put this file in the extensions/ subdirectory of your wiki, then edit the LocalSettings.php file to include it, followed by setting a variable to point to your BOINC project. The two lines to add look like require_once( "$IP/extensions/BOINCAuthPlugin.php" ); $BOINC_html='/usr02/pirates/html'; The path to the html can be absolute, or relative to the top-level directory of the wiki.

UserLogin Hook
To use BOINC for all authentication we have to redirect the wiki's normal mechanism for requiring a login. This is done via a "hook" -- a place in the code where it will run an optional function if one is provided. The BOINC authentication plug-in provides a hook function which causes the wiki to use the BOINC login page rather than using the wiki login page. However, MediaWiki does not (yet) have the proper hook in place to use this function, so you will need to install it yourself. Doing so is fairly easy, but requires editing the MediaWiki source code directly. And you have to repeat the process whenever you upgrade.

Here is how to install the hook:

$form = new LoginForm( $wgRequest ); if( !wfRunHooks('UserLogin', array(&$form)) ) return; $form->execute I proposed the addition of this hook to the MediaWiki developers but my request was turned down with no explanation. Until we can convince them to add this or something else to provide this functionality you will have to edit this file every time you upgrade your software. Or perhaps we can find another way to accomplish the same thing?
 * In the file includes/SpecialUserlogin.php find the function wfSpecialUserlogin and insert a hook called 'UserLogin' between the creation and execution of the login form.  The new code should look like this:

Edit System Messages
Various messages which are shown to users can be adjusted to make it clear that authentication is handled by the BOINC part of the site, and to make your access and editing policies clear. You should review the messages visible from Special:Allmessages, especially those related to logging in or editing. If one group of users is not allowed to create new pages or to edit pages then the system messages should explain that.

Policy Management
It is possible to have a user's permissions on the wiki controlled by information obtained from the BOINC project. So, for example, only BOINC participants who have Recent Average Credit (RAC) above a certain threshold may be allowed to edit or create a new page. Special users on the BOINC project (administrators or forum moderators) can be given special permissions on the wiki. You can easily make your own policy for how BOINC users may make use of the wiki.

You can modify the permissions policy on your project in one of two ways. You may edit the example which is contained in the plug-in code, or you can put your policy into a function called BOINCAuthPolicy in a file called BOINCAuthPolicy.php in your BOINC project directory.

Two examples make this clearer:

Example: Pirates@Home
Pirates@Home is a BOINC project used to test BOINC software and other new ideas, such as this authentication plug-in. The plug-in was tested extensively on Pirates@Home with a somewhat complex permissions policy based on BOINC user information, which is included in the plug-in as an example. The policy is that anybody on the Internet can read the glossary, and any authenticated user can contribute to an existing talk page. Only BOINC user with non-zero Recent Average Credit (RAC) can create a talk page or edit an article. Only users with RAC > 1.0 can create a new article. Discussion forum moderators are given permissions such as patrol, rollback, protect, and move to allow them to police the wiki. Users who are banned from the BOINC discussion forums are not allowed to edit any part of the wiki.

The policy is implemented by assigning BOINC users to permission groups named seaman, able_seaman, chief, officer, or brig. The permissions given to these groups are set in a separate file called PiratePermissions.php, which is included by LocalSettings.php</tt>. You can change the policy by changing the permissions assigned to these groups, and/or by changing the conditions for users to be assigned to the groups.

Example: I2U2
The mock-up web site for the I2U2 project at http://i2u2.spy-hill.net includes a wiki-based glossary which provides another example. The permissions policy is implemented from the file BOINCAuthPolicy.php by defining a function called BOINCAuthPolicy($boinc_user,$wiki_user)</tt>. The first argument is the user object for the user from the BOINC project, while the second argument is the user object for the same user for the wiki. The policy implemented here is simpler than the previous example. The BOINC-based project identifies users as teachers, students, or administrators using BOINC's 'special user' bits. These are used to assign the wiki user to an appropriate permission group.

Getting the source code
A stable version of this extension can be downloaded directly from http://www.spy-hill.net/help/boinc/BOINCAuthPlugin.php

Newer development versions or older versions can be obtained via CVS thus: cvs -d :pserver:anonymous@spy-hill.net:/usr/local/cvsroot/boinc checkout src/mediawiki The directory this creates will also contain a sample policy file, BOINCAuthPolicy.php</tt>, and a sample group permissions, in the file PiratePermissions.php</tt>, which you may find helpful.

The extension itself is licensed under the GNU General Public License (GPL), version 2. The sample policy and permissions files are licensed under the less restrictive MIT License.

How it Works
This section contains technical details about how BOINC authentication works and how this plug-in works to authenticate a BOINC user to the wiki. It's likely that this section is only of interest to MediaWiki or BOINC developers, or perhaps someone who wishes to write a different authentication extension.

Both the BOINC web pages and MediaWiki are written in PHP and use a MySQL database, but that is not really important -- the authentication mechanism would work even if this was not the case.

User tables
BOINC and MediaWiki both maintain their own user tables in their respective databases, and the tables are similar to each other, but not exactly the same. BOINC and MediaWiki treat user names differently. On the wiki, each user has a unique login name which cannot be changed, although they can change their "Real" name and "Nickname", which are what are shown to other users. In BOINC users are allowed to change their login names.

Because BOINC users can change their login names, BOINC keeps track of users with a unique identifier called an "authenticator", which is a 32 digit hexadecimal number. (In earlier times this was the only means of authentication to a BOINC project -- e-mail/password authentication was added later.)  We use the authenticator to associate a BOINC user with a wiki account. When a BOINC user accesses the wiki for the first time a new user entry is created for them in the wiki database. Their username on the wiki is their username on the BOINC project, but with any characters removed which are not allowed by the wiki. (If the BOINC name is empty after removing such characters then a generic default is generated.) The BOINC authenticator is stored in the wiki password field.

Since all authentication is done via BOINC, the user password field on the wiki would not be used. So we are free to use that field to store the BOINC authenticator, provided that there is no way that it can be overwritten (and the plug-in disallows such changes, so this is true). Then even if the user changes their BOINC name, we can look them up in the wiki user table via the authenticator. Whenever a BOINC user visits the wiki we first check for their authenticator in the password field of the user table, and use this to recognize returning users regardless of username.

E-mail addresses and verification
Both BOINC and the wiki keep track of the user's e-mail address. Every time the user starts a session on the wiki we copy over the e-mail address from the BOINC database. The user can change their e-mail address in their wiki preferences, but the change will only be for the current session. It will revert back to the value known to BOINC the next time a new session is started. (We need to find a way to remove this from the preferences or this could be confusing.)

BOINC had a mechanism for validating an e-mail account, but it has been removed in more recent releases, and in any case it simply stored the result as a boolean true/false value. The wiki software stores a timestamp of when the e-mail address was validated. So for now if the wiki does not have a validation timestamp and it detects that the BOINC project says the e-mail address has been validated then it writes the current time in the timestamp. This is not ideal, so you should not really trust e-mail validation right now.

I would like to see e-mail validation put back into BOINC, with a timestamp rather than just a bool, and I'll lobby the developers group to do so. (I can write the code, I just have to get them to agree to accept it.)

Cross project ID
Multiple BOINC projects can identify the same user across projects even if they use different user names on different projects by means of a "cross project ID" which is propagated between projects. This plug-in can only be used on a single BOINC project hosted on the same server as the wiki (at least for now), but in anticipation of the possibility of a multi-project wiki I store the cross project ID in the wiki in the user's temporary password field (which is otherwise unused, since BOINC handles all password authentication). Note that the cross project ID is considered public information, whereas the authenticator is supposed to be kept a secret.

Status Changes
If a user's status changes on the BOINC project (eg. they are banned on the forums) this will not necessarily be applied on the wiki side immediately. The BOINC code can force the user's status to be re-evaluated in the wiki by writing a timestamp to the wiki user's table. Sample code to do this is $MediaWikiTimestamp = gmdate( 'YmdHis', time); $MediaWikiUserTable= $wikiDB.".user"; $auth = $user->authenticator; $q = "UPDATE $MediaWikiUserTable SET user_touched=$MediaWikiTimestamp " ." WHERE user_password='$auth' "; mysql_query($q); At present there is nothing like this in the current BOINC distribution.

Shared Session
The BOINC project and the wiki can share the same PHP session, which allows the authentication credentials to be obtained from the session rather than from cookies. It is not clear that this is necessary or any better than cookies, but it works. It requires a modification of the BOINC PHP code to give the BOINC session a name, such as "boinc_session". Then the wiki can be told to use the same session by adding to the file LocalSettings.php</tt> a line of the form $wgSessionName     = "boinc_session"; //to match the BOINC project Since the wiki will also use the same cookies BOINC uses for staying logged in on a particular browser it is not clear that there is a good reason to go through all this trouble, nor is it clear that I need to mention it at such great length in this documentation.

Known Problems
There are a few subtle points which may cause problems. While they can't be "fixed" anytime soon, it helps to know about them:


 * If a user's status on the BOINC project changes (perhaps their RAC has dropped below a threshold, or they were suspended and the suspension is over) then their status on the wiki may not be changed immediately. The change may be delayed until the next recheck (set by RECHECK_INTERVAL, nominally 1 hour but you can change this).   At the worst it will take another hour (or whatever the interval is set to) until their status changes.


 * BOINC and the wiki handle validation of e-mail addresses differently. The wiki stores a timestamp of when the e-mail address was validated.  BOINC recently removed e-mail validation entirely, but if you keep that field in your project database it is still just a yes/no flag, not a timestamp.  So when we first detect that the BOINC flag is "yes" then we write the current time into the wiki timestamp.   I hope to lobby the BOINC developers to bring back e-mail validation, with a timestamp rather than a bool.