Extension:WhiteList

From MediaWiki.org

Manual on MediaWiki Extensions
List of MediaWiki Extensions

WhiteList Release status: beta
Implementation	User rights, Special page, Notify, Database
Description	Allows restrictive access to certain Mediawiki pages with a robust whitelist option.
Author(s)	Paul Grinberg, Mike Sullivan
Version	v0.8.7 (April 15, 2008)
MediaWiki	1.6.0+
License	GPL
Download	Download Here Read Changelog
Added rights	restrictedtowhitelist, editwhitelist
Hooks used	userCan PersonalUrls

Project groups in a variety of fields have adopted wikis for collaboration and documentation. Under some circumstances (particularly in corporate environments), it is necessary to restrict access to this information.

There are several ways to restrict access when using a MediaWiki installation. One such technique is using Extension:Blacklist to blacklist certain pages. However, when a user needs to be restricted to only a few specific pages, the blacklist approach becomes cumbersome. Instead, a whitelist can be used to define these restrictions.

Extension:WhiteList allows per-user whitelist for selected users, while the other users retain full access to all pages. This allows only members of the core project group to have access to all information, while other contributors have access to certain pages.

Extension:WhiteList requires little administration time, typically a few minutes for each restricted user.

Extension:WhiteList is provided under the GNU General Public License (v2.0).

[edit] Description

Extension:WhiteList adds two new user rights:

editwhitelist

User has permission to modify the whitelists of existing users using a new special page (Special:WhitelistEdit - screenshot below).

restricttowhitelist

User is only allowed to view and edit pages as defined by the user-specific whitelist. All other pages are blocked. All restricted users will have a new Personal Tab called My Pages which will list only the pages they have access to. Restricted users may also request access to additional pages using this tab. (Such requests will generate an e-mail to the user's Manager.)

Extension:Whitelist adds two default groups which use these permissions. The Manager group has the editwhitelist user right. The Restricted group has the restricttowhitelist user right. Users with the userrights permission (assigned to the bureaucrat group by default) can assign users to these groups using Special:Userrights on their local MediaWiki installation.

When creating/editing a user's whitelist, the Manager defines specific pages which are visible for each restricted user. For each page, the Manager chooses whether the user can edit or simply view the page. The Manager can optionally define an expiration date for each whitelist page entry. (A sample screenshot of this interface is below.)

[edit] Manager Usage: Whitelist Access Editor

The Whitelist Access Editor is divided into two sections. The top portion entitled Current information for Some User details all of the currently whitelisted wiki pages for the selected restricted user. The bottom portion entitled Add new pages to Some User's whitelist is for defining new whitelist pages for the currently selected restricted user.

[edit] Current Whitelist Pages

This table contains 6 columns. Each row corresponds to one whitelisted page for the currently selected restricted user. The title of this page is in the Wiki Page column. A manager can verify that this page really should be whitelisted by clicking on the title which takes then to that page. The other columns to the right are detailed below:

• Access Type - lists what kind of access was given to the resitricted user for this page. There are only two options: edit and view.
• Expires On - lists when the restricted user's whitelist access for this page will automatically expire. This could be a date, either in the future, which means that the restricted user still has the ability to access that page, or it could be a date in the past, which means that the restricted user's whitelist access to this page has expired. A blank entry means that there is no expiration date for access of this page.
• Last Modified By - lists the name of the manager who last modified the permissions this restricted user's access to this page.
• Last Modified On - lists the date on which the manager who last modified the permissions this restricted user's access to this page did so.

The manager interacts with this restricted user's current permissions by selecting one or more pages in the Modify column by clicking on the checkboxes. In case the manager wants to interact with all listed pages at once, they can click on the All or None links in the column heading which checks or clears all checkboxes, respectively. The action to perform on the pages checked in the Modify column are detailed below the table. A manager can select only one of the following actions:

• Change Expiry Date - set the Expires On date for all selected pages to the date defined in the New Date field to the left. For manager's convenience, clicking on New Date brings up a JavaScript calendar. Remember, the New Date can be left blank to indicate that page access will never expire.
• Set to Edit - set the Access Type permissions for all selected pages to Edit.
• Set to View - set the Access Type permissions for all selected pages to View (read only).
• Remove - removes all selected pages from the restricted user's whitelist

Once the pages and the action are defined, the manager needs to click on the Process button.

[edit] New Whitelist Pages

This table contains a textbox which can be used to add new wiki pages to the restricted user's whitelist access. The entries are all treated as wiki titles (both articles and categories, both existent and nonexistent) and are parsed as one title per line. It is also possible to use the % or the * character as a whildcard when entering new pages.

Once all new pages are defined, the manager needs to define what kind of access to give to the restricted user for all of these pages. The manager can define:

• Expiry Date - defines when the restricted user's access to all of the newly defined pages will expire. Remember, the manager can enter the date either with the JavaScript calendar by clicking on the Expiry Date link, or they can leave it blank to make the access never expire.
• Set to View or Set to Edit - defines whether the access type for all newly defined pages should be View or Edit.

Once the pages and the action are defined, the manager needs to click on the Process button.

The wildcard feature should be used with caution because it may open up access to more pages than what is truly needed. That is why upon pressing the Process button, the manager can review their submission and see the expanded list of current pages that match the wildcard pattern. There are a couple of caveats with the usage of wildcards:

1. Currently, usage of wildcards on the Media and Special namespaces is not allowed.
2. If the first character is a wildcard, then it is assumed that this pattern should match all namespaces
3. If a page is whitelisted, then its sibling talk page is also whitelisted (and vice versa)
4. if a page is whitelisted and it is a redirect to another page, that other page will also be whitelisted

[edit] Restricted User Usage: My Pages

As it was pointed out earlier, restricted users can find out which pages they are restricted to by clicking on their My Pages personal URL (typically in the upper right hand corner of every page). Clicking on this link actually takes them to Special:WhiteList page.

As can be seen above, the restricted users will see not only the pages that were explicitly whitelisted for them by a manager, but also whitelisted pages implicit in the extension (see #Advanced Extension Configuration for details on configuring $wgWhitelistOverride). Additionally, restricted users can request access to more pages by filling out the form on the right which will send the selected manager an email notifying them of the request.

This page is effectively blocked for every non-restricted users because for them it does not make sense to see page restrictions since they are not restricted. However, non-restricted users may have a need to sometimes see which pages restricted users are allowed to see. To do so, non-restricted users can go do Special:WhiteList/userid where userid is the user ID of a restricted user. Note: this functionality is different than the one allotted for managers via Special:WhiteListEdit; managers can add/remove/change permissions for a restricted user's whitelist, whereas non-restricted users who are not managers can only view restricted user's whitelist.

[edit] Installation

[edit] Install Extension:Usage Statistics

By default, the WhiteList extension will try to use pretty calendar entry shown in the screenshot above. To enable the calendar widget in the Whitelist Access Editor, install Extension:Usage Statistics. Note: In the installation instructions for usage statistics, installing gnuplot is recommended. However, since UsageStatistics is only needed for one function within Whitelist, you don't actually have to install the gnuplot extension if you don't want to. However, not doing so will impair the functionality of the UsageStatistics extension, if you ever wanted to use it.

The requirement for the Usage Statistics extension is optional and can be disabled via the $wgWhitelistUsePrettyCalendar variable (see below).

[edit] Update Common.css/.js

Verify that your MediaWiki:Common.css and MediaWiki:Common.js pages contain a section on Dynamic Navigation Bars. If they do not, or if those pages simply do not exist, then copy the pages from Wikipedia MediaWiki:Common.css and MediaWiki:Common.js.

[edit] Install Extension:Whitelist

Download all extension files from SVN and place them in the extensions/WhiteList/ directory.

[edit] Create the MySQL table

To create a MySQL table, you need to have console access to your server. First, open up your console. Type:

use nameofyourdatabase

The database will now be selected. Paste the following text into the console and press enter. Make sure to use the appropriate $wgPrefix. In this example, we used wiki_ as the $wgPrefix.

CREATE TABLE IF NOT EXISTS `wiki_whitelist` (
  `wl_id` int(8) NOT NULL AUTO_INCREMENT,
  `wl_user_id` int(5) NOT NULL,
  `wl_page_title` varchar(255) NOT NULL,
  `wl_allow_edit` int(1) NOT NULL,
  `wl_expires_on` varchar(19) DEFAULT NULL,
  `wl_updated_by_user_id` int(5) NOT NULL,
  `wl_updated_on` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY  (`wl_id`)
) ENGINE=MyISAM  DEFAULT CHARSET=latin1 AUTO_INCREMENT=30 ;

[edit] Setup the system messages

Go to your Special:Allmessages page and set an appropriate message for

• badaccess-group1
• badaccess-group2
• badaccess-groups

These are the messages displayed by MediaWiki when Extension:WhiteList denies page access to a restricted user.

[edit] Enable the extension

Add the following text to your LocalSettings.php

require_once( "$IP/extensions/WhiteList/SpecialWhitelistEdit.php" );

[edit] Configure Users

Before the extension can be used, a sysop has to add the desired users to the manager group. Note, by default, a sysop will not have the necessary permissions to see the manager's Special:WhiteListEdit page. So, it might be a good idea to add your sysops to the manager group also.

Next, assign whomever you want to restrict to the restricted group. Now, your managers can create and modify the restricted users' whitelists using Special:WhitelistEdit.

[edit] Advanced Extension Configuration

The following variables can be defined in LocalSettings.php to modify the behavior of Extension:Whitelist:

[edit] Security Issues

This is an attempt to document how the Whitelist extension copes with various security concerns described at Security issues with authorization extensions. Note that, while this system is in production use, the extension authors make no warranty that the following information is complete or accurate (although we believe it to be so). If you find any security issues with this extension that are not described here, please let us know on the talk page.

There is a greater change of security issues in the read protection system, due to MediaWiki's architecture. So, denying read access should be seen as a "nothing to see here, move along," sort of thing rather than a absolute guarantee of secrecy.

[edit] To Do

This extension is still actively being worked on, so there may be a number of improvements yet to come. The short list of improvements includes:

• Highlight the expiry dates that have expired in red
• When a wildcard is used to enable access to a set of pages, it may pull in one too many pages. Currently, there is no easy way to work around that. One possibility is to allow managers to also define BlackListed pages which would take precedence over whitelisted pages. This way, the manager could define a generic wildcard pattern and then also specify the couple of pages that must be explicitly blacklisted.
• restricted users cannot upload a new image even if that image is should already be whitelisted.

[edit] History