Extension:WhiteList
From MediaWiki.org
For further details, see Security issues with authorization 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 | |
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).
Contents |
[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:
- Currently, usage of wildcards on the Media and Special namespaces is not allowed.
- If the first character is a wildcard, then it is assumed that this pattern should match all namespaces
- If a page is whitelisted, then its sibling talk page is also whitelisted (and vice versa)
- 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:
| Variable | Default Value | Description |
|---|---|---|
| $wgWhiteListRestrictedGroup | 'restricted' | Name of the restricted user user right. |
| $wgWhiteListRestrictedRight | 'restricttowhitelist' | Name of the restricted user user right. |
| $wgWhiteListManagerGroup | 'manager' | Name of the manager user group. |
| $wgWhiteListManagerRight | 'editwhitelist' | Name of the manager user right. |
| $wgWhitelistOverride['always']['read'] | array() | List of pages which are always readable by restricted users, even if the page is not on the restricted user's whitelist. These are typically pages required for basic MediaWiki and user functionality. |
| $wgWhitelistOverride['always']['edit'] | array() | List of pages which are always editable by restricted users, even if the page is not on the restricted user's whitelist. |
| $wgWhitelistOverride['never']['read'] | array() | List of pages which are never viewable by restricted users, even if the page is on the restricted user's whitelist. |
| $wgWhitelistOverride['never']['edit'] | array() | List of pages which are never editable by restricted users, even if the page is on the restricted user's whitelist. |
| $wgWhitelistUsePrettyCalendar | true | Used to define if the extension should use pretty calendars for date entry (requires Extension:Usage Statistics - see above). |
[edit] Security Issues
For further details, see Security issues with authorization extensions
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.
| Function/Test | Check for | WhiteList extension |
|---|---|---|
| Inclusion/transclusion |
|
Potential security issue. Transclusion is not affected by the UserCan hook, so the WhiteList extension cannot block protected pages from being transcluded. Suggested configuration is to use $wgNonincludableNamespaces (MW 1.10+/rev:19934) to only allow transclusion of the Template: namespace. In previous MW versions, the NonincludableNamespaces extension can fulfill the same purpose. |
| XML export (Special:Export) | Is it possible to export the contents of a protected page? | Potential security issue. Using MW 1.10 (rev:19935), It is not possible to export the contents of a protected page. In previous MW versions, users with access to Special:Export can export any protected page. (A workaround would be to keep Special:Export blocked). |
| Atom/RSS feeds | Does the article get delivered? With diff or full content? There are two feeds, one in the Recent changes special pages and other on the page history. Additional feeds may be provided by extensions. |
Potential security issue. This was addressed through a combination of fixes in MW 1.10 (rev:19944) and MW 1.12 (rev:25944). In previous versions, it is recommended that users disable feeds to eliminate this security issue. (see Disable feeds) |
| Listings & search |
|
Potential security issue. In MW 1.10+ (rev:21821), the search page no longer shows excerpts from pages that are not readable (but titles will still be listed). In previous versions, the Special:Search page should not be whitelisted if you do not want page excerpts to be displayed in a search. |
| Diff & revision links |
|
No known issues. This should be OK on recent versions of MediaWiki, according to Security issues with authorization extensions. |
| Action links |
|
No known issues. This should be OK on recent versions of MediaWiki, according to Security issues with authorization extensions. |
| Related rights |
|
No known issues.
|
| Author backdoor | Some extensions always allow the original author of a page to access it, ignoring later access restrictions. | No known issues. The WhiteList extension does not feature an author backdoor. |
| Caching | $wgEnableParserCache (enabled by default) caches articles between users. $wgEnableSidebarCache (not enabled by default) performs a similar function for the sidebar. If the extension could send different pages to different users, it might be incompatible with this caching. | Unknown risk. We have not experienced exposure of articles due to MW caching, but we will investigate this issue further. |
| Files & Images |
|
Potential security issue. Since uploaded files are normally served directly by the web server, not through MediaWiki, it's not easily possible for extensions to prevent access. The extension authors used Manual:Image Authorisation to set up access restrictions for images, although this access cannot be set up on a per-image, per-user basis. |
| Redirects |
|
No known issues.
|
| Edit Section |
|
No known issues. This extension uses the userCan hook, which handles this issue. |
| Other extensions |
|
If the extension uses the userCan hook, WhiteList will provide security functionality (although the exact functionality depends on the implementation of the extension). If the extension uses a special page, that special page could be blocked using this extension. For other extension, the user is responsible for understanding and reviewing other extensions on their MW installation to understand their risk. |
[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
| Revision | Release Date | Description |
|---|---|---|
| 0.8.7 | April 15 2008 |
|
| 0.8.6 | April 14 2008 |
|
| 0.8.5 | April 4 2008 |
|
| 0.8.4 | March 13 2008 |
|
| 0.8.3 | March 12 2008 |
|
| 0.8.2 | March 11 2008 | minor bug fix; used to sometimes display "Bad Title" in overview
|
| 0.8.1 | March 10 2008 |
|
| 0.8 | March 10 2008 |
|
| 0.7.1 | Feb 23 2008 | fixed a typo which resulted in an undefined function error |
| 0.7 | Feb 19 2008 |
|
| 0.6 | Feb 15, 2008 | give the restricted users the ability to request page access |
| 0.5 | Feb 15, 2008 |
|
| 0.4 | Feb 12, 2008 |
|
| 0.3 | Feb 8, 2008 | Initial publication on MediaWiki |

