Open main menu


MediaWiki extensions manual
Crystal Clear action run.svg
Release status: unmaintained
Description Extends native MediaWiki protection to allow article's viewability to be restricted
Author(s) Aran Dunkley (Nadtalk)
Latest version 5.1.0 (2012-01-19)
MediaWiki 1.17.x–1.24.x
Database changes No
License GNU General Public License 2.0 or later
Translate the SimpleSecurity extension if it is available at
Check usage and version matrix.

The SimpleSecurity extension extends native MediaWiki protection to allow article's viewability to be restricted.

The general problem with implementing a proper security solution in MediaWiki (giving rise to the scary looking warning box shown above) is that although most of the actions one can perform on articles can be restricted easily, the ability to read content cannot be easily restricted on a per-title basis. The reason reading is difficult to restrict is because it's an operation which is not just performed via one action, but rather that many different actions, special-pages and extensions access article content and display it in diverse ways. To make matters worse, many of these diverse means of article access are done by querying the database directly rather than going via the Article class.

See the technical details section below for more details on this problem and the solution that SimpleSecurity above version 4 uses to overcome it. The solution is disabled by default (see configuration settings below), it is still functional without it but there are then simple means available to view restricted content such as by exporting it or transcluding it in another page.

If you're using a version of MediaWiki prior to 1.17.0 then you'll need to use SimpleSecurity 4.x which is available from the OrganicDesign extensions Subversion repository.

If you're using a version of MediaWiki prior to 1.12.0 then you will need to use an older version of this extension, but please note that versions prior to 4 are unstable, unreliable and are not used in the same way as version 4 and above. The last 3.x version is available here



Create a SimpleSecurity folder in your extensions directory. Download this extension from the OrganicDesign site and add it to your extensions directory. Then include it in your LocalSettings.php file as in the following example.

$wgSecurityUseDBHook = true; # Add this to enable the experimental DB hook for stronger security
$wgSecurityUseDBHook = true; # NOTE: this directive MUST be used before the require_once directive if you're using SimpleSecurity 4.x
$wgSecurityRenderInfo = true;
$wgSecurityAllowUnreadableLinks = false;
$wgPageRestrictions['Category:Servers']['read'] = 'sysop';
# Version 5.0.4 requires the following sequence of statements (a different sequence does not work!):
$wgSecurityUseDBHook = true; # NOTE: this directive MUST be used before the require_once directive if you're using SimpleSecurity 4.x, 5.0.4
$wgSecurityRenderInfo = true;
$wgSecurityAllowUnreadableLinks = false;
$wgPageRestrictions['Category:Servers']['read'] = 'sysop';


SimpleSecurity4 extends the way the inherent MediaWiki permissions and restrictions system works. Following is a list of the specific functionalities which are added or extended and how to use them.

"Read" restriction added to protect tabEdit

It seems that the main code-base development won't have a solution to the read problem for some time, but the current method of article protection already allows for restricting edit, create and move actions by group, and allows for the possibility of other actions to be handled, so the approach that Simple Security 4 has taken is to add a new restriction to the existing protection page called read which you can see in the images below which show the protection page with and without Simple Security installed.

Protection form without SimpleSecurity Protection form with SimpleSecurity

The image on the right shows the additional read restriction has become available. Also the tick-box which is used to allow adjustment of the restrictions individually is changed to be more general so it will be appropriate for any number of additional restrictions.

Extra groups added to protection tabEdit

To have extra groups available in the select box for each action (like "Security test group" in the picture above), add them to the $wgSecurityExtraGroups array in your LocalSettings.php file, for example:

$wgSecurityExtraGroups = array(
    'foo' => 'Foo group',
    'bar' => 'Bar group'

The index should be the internal name of a group (as seen in the user rights special page etc), and the value is a more friendly name shown in the protection form. There should not be any actions specified in that array it's just for adding groups into the protection form.

In MediaWiki 1.13.x you can only assign extra groups that you belong to. Extra groups that you do not belong to will show up as blanks in the group selection boxes. (disc)

Restriction by category & namespaceEdit

Category-based permissions are now handled from LocalSettings.php for efficiency reasons and will not inherit more than a single level. Namespace permissions are also supported, both are defined in the $wgPageRestrictions array which uses a format as follows:

$wgPageRestrictions['Category:Our_people']['edit'] = array('sysop', 'management');
$wgPageRestrictions['Namespace:Special']['read'] = 'user';

This example restricts article in Category:Our people such that only members of groups sysop and management can perform "edit". And "read" can only be performed by user for all articles in the "Special" namespace.

Note that categories which include a space must use an _ (underscore) in place of a space as in Category:Our_people above. Please also note that English descriptions such as “Category” or “Namespace” must be used no matter which language is being utilised on the wiki and which was used to set it up.

Restrictions set in $wgPageRestrictions can be overridden by those in the article's protect tab.

Note that even if you restrict "read" action for a category this won't prevent to read the list of pages, categories and files belonging to that category!

Security-based conditionsEdit

SimpleSecurity adds two parser-functions for rendering content conditionally based on security permissions or group membership. Here's a couple of examples,

{{#ifusercan:edit|Main page|Check the homepage editing [[todo list]]!|check the [[latest news]]!}}

This example renders a link to a todo list if the user has permission to edit the main page, otherwise a link to the news is rendered instead.

{{#ifgroup:sysop|Check the homepage editing [[todo list]]!|check the [[latest news]]!}}

Here's the same example again, but this time the conditions is whether or not the user belongs to the sysop group. A comma separated list of groups can be used for the group parameter in which case the condition will evaluate to true if the current user belongs to any of the groups in the list.

  • The last parameter is optional and defaults to an empty string if not supplied
  • Extension:TreeAndMenu can be used with these options since it doesn't render nodes with no content

Security informationEdit

Articles which exhibit restrictions either from the protect tab or from $wgPageRestrictions can optionally have the information displayed by setting the $wgSecurityRenderInfo global variable to true. A link will be rendered entitled Security information which when clicked will reveal (or hide) the list of restrictions exhibited by the article. The show/hiding link is of the CSS id security-info-toggle, and the list of restrictions is contained in a div of id security-info, so a custom style can easily be applied by adding some CSS rules to your MediaWiki:Common.css article. For example the following rule gives a border and background to the listed rules when they are visible.

#security-info-toggle {
    background: transparent url(/wiki/skins/monobook/lock_icon.gif) no-repeat scroll left center;
    padding-left: 16px;
#security-info {
    border: 1px solid #ccc;
    background: #eee;

Unreadable linksEdit

Still has some bugs to iron out

If the $wgSecurityAllowUnreadableLinks global is set to false (default), then links to local articles which the current user does not have permission to read are rendered as plain text rather than a hyperlink.


The image above shows a small fragment of a recent changes list. Notice that the Sandbox article title and its diff and hist show up grey and are not links, their style can be set in CSS by addressing the unreadable class attribute.

Global security settingsEdit

Here are the global variables which affect the operation of the extension. These should be set in your LocalSettings file after the include of the SimpleSecurity.php script.

Variable Default value Meaning
$wgSecurityUseDBHook false Specifies whether or not the voodoo should be used to intercept the database queries. To enable this, it must be set to true before the SimpleSecurity.php inclusion.
$wgSecurityRenderInfo true Renders security information for articles for which restrictions apply
$wgSecurityAllowUnreadableLinks false Whether or not a hyperlink to a page which is not readable by the current user should still render as a link
$wgSecurityMagicIf ifusercan The name for doing permission-based conditional content
$wgSecurityMagicGroup ifgroup The name for doing group-based conditional content
$wgSecurityExtraGroups empty An array of the additional groups which should be available in the protect tab
$wgSecurityGroupsArticle empty Additionally extra groups can be supplied in an article (default namespace assumed is "MediaWiki")
$wgPageRestrictions empty An array of category and namespace based restrictions

DB Hook: Technical detailsEdit

To allow restrictions on the reading of article content requires a hook at a very low-level in the programming which is common to all the kinds of operations involved in the retrieving of article content. The MediaWiki code is written to support a number of different database servers each with their own implementation of the SQL language, and it has also been designed to allow a wiki's database to be served from many servers concurrently. To achieve this, a Database class has been created to abstract the database access functions from the SQL langauge specifics. All database interaction is handled via the methods of the Database class, and specifically, the only way that any legitimate MediaWiki code would obtain any article content is through the fetchRow and fetchObject methods.

So to really solve the per-title read-restriction issue, some of the methods of the Database class would need to be intercepted. There are no official hooks in the methods we need to intercept, so instead hooks are added in a sub-class of the database type specified in $wgDBtype called DatabaseSimpleSecurity.

All text content is held in the old_text field of the text table, so the row-reading needs to be intercepted. But the SELECT queries also have to be adjusted to ensure that the old_id field is available along with old_text otherwise it cannot be established whether or not the text is allowed to be viewed (since the id is needed to relate the text fragment with a current article title). The query method of the database class has been overridden to patch the SQL, and fetchObject has been overridden to replace the content of the requested old_text field if it should not be accessible.

Patching SQL statements directly is not an ideal solution as it's inefficient and lacks portability, but we have a number of clients running mediawiki on their intranets who have been in dire need of a reasonable means of restricting their content on a per-title basis, but are also dead-set on sticking with MediaWiki. Unfortunately this is the only solution we've been able to come up with for them, but testing so far is showing positive results and should be no problem for all but the very high traffic sites.

For more information, see the development notes at OrganicDesign:Extension:SimpleSecurity.php.


  • $wgPageRestrictions
    • doesn't work for '*' group, for example $wgPageRestrictions['Category:Public']['read'] = '*' fails.
    • neither does '*' work for the area to restrict, e.g. $wgPageRestrictions['*']['read'] = 'employees'
    • The name of the "Main" Namespace is an empty string, so if you want to limit access to all pages in Main you need to specify $wgPageRestrictions['Namespace:']['read'] = 'employees'

See AlsoEdit