Extension:PageSecurity

Warning
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Introduction
PageSecurity is an extension to MediaWiki that implements page access control. It can enforce read and write protection for selected pages or for sets of pages. User access is controlled by membership in user groups.

The protection is applied in addition to the normal MediaWiki access protection. If MediaWiki denies access to a page, it will stay denied. If MediaWiki grants access, the PageSecurity extension will apply additional rules.

'''You are advised to install an appropriate document management package [Peter Blaise asks: such as ...?]. MediaWiki was not written to provide per-page access restrictions, and almost all hacks or patches promising to add them will likely have flaws somewhere, which could lead to exposure of confidential data. We will not be held responsible should a password or bank details be leaked, leading to loss of funds or one's job. robchurch''' | talk 06:14, 8 November 2006 (UTC)

If, even warned, you feel MediaWiki's features are useful for your needs and the potential damage in case of leaks is low, feel free to try this extension. At your own risk. For starters, you can check it against the known security issues with authorization extensions.

Features

 * Named security definitions.
 * Security definitions can be applied to namespaces, templates, page titles and page text.
 * Support for MediaWiki user groups.
 * Separate permissions for reading and writing.
 * Supports "allow" and "deny" specifications, giving precedence to "deny".
 * Security definitions can be inherited.
 * Supports a default security definition.
 * Search and diff work (for authorized users).
 * Can show protection information on page footer.
 * Optional transclusions.
 * Logo can reflect page security definition.
 * Protected MediaWiki actions:
 * Read page.
 * Transclusion (even nested).
 * Edit page.
 * Preview page edit (even with transclusion).
 * Create new page.
 * Move or rename page.
 * View page history (including differences and Atom feed).
 * Access discussion page.
 * Render page.
 * View raw page content.
 * Search.
 * Export XML.
 * Get article content.

Limitations

 * Page titles are not hidden.
 * Atom and RSS feeds must be disabled.
 * Uploaded files and images are not protected.
 * Requires a few simple patches on MediaWiki.
 * Write access to the discussion (talk) area requires write access to the page. This is a MediaWiki restriction that can be circumvented using the Talkright extension.
 * Requires more processing power than standard MediaWiki. Pages can't be cached, and the full text of the articles is searched for protection patterns. Performance should be adequate for a user base of a few thousand, but requirements might be steep for very heavy load.
 * Author access: This extension does not implement a feature to always allow full access to the original author of a page. This is a deliberate design decision to prevent security problems that this feature could cause.
 * All messages are in English.

Usage scenarios

 * Present one home page for employees and another for customers.
 * Allow customers to see released documentation and employees to edit it.
 * Hide documentation from customers while it is still being written collaboratively by the employees.
 * Hide internal documents from customers.
 * Create private subject areas within a corporate wiki.

Installation and upgrade

 * 1) Backup your wiki folder and database.
 * 2) Install the patches.
 * 3) Install the PageSecurity extension or upgrade from a previous version of the PageSecurity Extension.

Configuration
This section describes configurations that must be done once to use the PageSecurity extension.

Basic user rights
These configurations are not required to use the PageSecurity extension, but they can be helpful.

Insert in LocalSettings.php:

$wgGroupPermissions['*']['read'] = false;
 * 1) require that users log in to read

$wgGroupPermissions['*']['edit'] = false;
 * 1) require that users log in to edit

$wgWhitelistRead = array( "Main Page", "Special:Userlogin", "-", "MediaWiki:Monobook.css" );
 * 1) allow these pages for anonymous users

$wgShowIPinHeader = false;
 * 1) remove the link to the talk page for non-logged in users

See wgGroupPermissions and User rights to learn more about MediaWiki group permissions on top of which the PageSecurity extension works.

Create user groups
Access will be granted or denied to user groups, not to individual users. So it is necessary to create these groups.

Insert in LocalSettings.php:

$wgGroupPermissions['Employees']['read'] = true; $wgGroupPermissions['Customers']['read'] = true; $wgGroupPermissions['Guests']['read'] = true; $wgGroupPermissions['Documentation']['read'] = true; $wgGroupPermissions[utf8_encode('Façade')]['read'] = true;
 * 1) Create user groups

Use utf8_encode if the group name contains special characters.

These groups are already created and have special meanings for MediaWiki:
 * *: Any user. May be referred to as "all" in security definitions.
 * user: Authenticated users.
 * bureaucrat: Users that have user management rights. See Wikipedia:Bureaucrats.
 * sysop: System administrators. Perform wiki maintenance. See Wikipedia:Administrators.
 * bot: A software that reads or writes wiki pages.

Assign users to groups
Use the Special:Userrights page to make each user a member of the groups he should belong to. You must have bureaucrat rights for this.

Optionally, you can write a program to insert records directly into the "user_groups" table on the wiki database.

For help on assigning bureaucrat and other rights to users see User rights and Setting user rights in MediaWiki.

Disable feeds
The Recent changes and New pages special pages can publish page text as RSS and Atom feeds. The code could be patched to verify user rights. But right now, the workaround is to completely disable these feeds.

Insert in LocalSettings.php:

$wgFeedClasses = array;
 * 1) Disable feeds

Disable cache
Insert in LocalSettings.php:

$wgEnableParserCache = false; $wgCachePages = false;
 * 1) Disable cache

Activate the PageSecurity extension
Insert in LocalSettings.php:

include_once('extensions/PageSecurity.php');
 * 1) Activate the PageSecurity extension:

Error page
The default MediaWiki access restriction message is not well suited for the PageSecurity extension. It is advisable to create a custom error message.


 * 1) Create a new page for the error message. For instance, its title can be "Access restricted".
 * 2) Insert some text like "Access to this page is restricted." and save the page.
 * 3) Insert this line in the LocalSettings.php file. Change "Access restricted" to the page title:

$wgPageSecurityErrorPage = "Access restricted";

Usage
This section describes the configuration of the access restriction rules. These configurations usually change over time as the needs evolve.

Security definitions
Security definitions are named access restriction rules that can be applied to pages. They are created as XML tags on wiki pages. They can be in several pages or all in one page.

Instructions:


 * 1) Create a new page. Use an appropriate title. For instance, "Security definitions".
 * 2) Insert the text of the security definitions.
 * 3) Save the page.
 * 4) Protect the page so only sysops can edit it (using the MediaWiki Protect command).

This sample assumes that users are assigned to groups named "Employees", "Customers", "Documentation" and "Guests":

 all Employees 

 all Guests 

 Employees, Customers Documentation 

After saving the page, this result will be shown:


 * Security definition Default:
 * This page can be read by all but only employees can edit it.
 * read: allow all.
 * write: allow Employees.
 * Security definition Free access (inherits from Default):
 * This page can be read and written by all except guests.
 * read: allow all.
 * write: allow Employees, all except Guests.
 * Security definition Official documentation:
 * This page can be read by employees and by customers. Only the documentation team can edit it.
 * Logo: http://www.server.com/wiki/uploads/9/9e/Logo-official-documentation.png
 * read: allow Employees, Customers.
 * write: allow Documentation.
 * Security definition Official documentation:
 * This page can be read by employees and by customers. Only the documentation team can edit it.
 * Logo: http://www.server.com/wiki/uploads/9/9e/Logo-official-documentation.png
 * read: allow Employees, Customers.
 * write: allow Documentation.
 * read: allow Employees, Customers.
 * write: allow Documentation.
 * write: allow Documentation.

The format of the security-definition tag is:
 * name: An identification that will be used internally to assign security definitions to pages.
 * base: Optional. A name of a previously defined security definition that should be inherited by the current one. Several levels are allowed. The rules of the base security definition are merged into the derived security definition.
 * notice: Optional. A textual message that can be displayed in the footer of the protected pages.
 * logo: Optional. A URL of an image to be used as a logo for the pages under this security definition. This feature can be used to give a visual hint to users about the security level of a page. It can prevent editing mistakes.
 * allow element: Specifies an access granted rule. Access must be explicitly granted.
 * action: "read" or "write". "read" grants access to the page contents. "write" allows create, edit, move and talk actions. "read" access is necessary to be able to have "write" access.
 * groups: Comma-separated list of user groups that the rule applies to.
 * deny element: Specifies an access denied rule. Denial has precedence over granting.
 * action: "read" or "write". "read" denies access to the page contents. "write" denies create, edit, move and talk actions. If "read" access is denied, so will be "write" access.
 * groups: Comma-separated list of user groups that the rule applies to.

Page protection expressions
The security definitions are applied to pages through page protection expressions.

These expressions look for patterns in the page title or page contents. When a pattern is found, the corresponding security definition is applied to the page.

The page protection expressions are arrays in this form:

array(,, )

Where:


 * security-definition: The name of the security definition that will be used if the expression is true for the page (equals tag name in paragraph ).
 * subject area: The area of the page that must be searched for this expression. Either "title" to search in the page title or "content" to search in the page content.
 * pattern: A regular expression pattern. If this pattern matches the subject, the expression will be applied to the page. Do not include pattern delimiters or options. The search options that will be used are: search through line breaks and ignore case.

The page protection expressions are declared like this, in LocalSettings.php:

// Use Free Access security definition to allow access to help pages to everyone, editable by all but guests // apply security definition to pages in Help namespace (^ matches the start of the subject) $wgPageSecurity[] = array("Free Access", "title", "^Help:");

// Use Default security definition to allow only employees read/write, but all read // apply security definition to pages that include the Restricted template $wgPageSecurity[] = array("Default", "content", "");

// Use Official Documentation policy // apply security definition to any page with the word "manual" in the title $wgPageSecurity[] = array("Official Documentation", "title", "manual");

Use utf8_encode if the security definition name contains special characters. Like this:

$wgPageSecurity[] = array(utf8_encode("Façade"), "title", "anything");

The pattern does not need utf8_encode.

Only the first pattern found is considered for each page. So the order of declaration is significant.

Important: Make sure a protection expression allows read access to the error page for all. Otherwise an infinite redirect loop will be created.

Default security definition
Optionally, a default security definition can be specified. If defined, it will be used if no page protection expression matched a page. If not specified, only the normal MediaWiki access protection will be applied.

To define a default security definition, insert in LocalSettings.php:

$wgPageSecurity[] = "Name of a security definition";

Security templates
Although not required to use the PageSecurity extension, security templates are very helpful.

They are normal templates that are applied to all pages that should be protected by a security definition.

They can also be used to assign categories to pages and to insert a text or an image on the page indicating its category or its protection level.

For example:

This page is part of the official documentation of the company's products. $wgPageSecurity[] = array("Official documentation", "content", "");
 * Create a template named "Template:Official documentation".
 * In the template, insert something like this:
 * Use this template on all pages that belong to the official documentation category. That is, use   instead of   .
 * Create a page protection expression to assign the "Official documentation" security definition to all pages that include the "Official documentation" template:

Now, you know that all pages that are in the "Official documentation" category and have the standard visual identification (the text or image used in the template) are protected according to a specific security definition.

Optional transclusions
When a page uses a transclusion that the user does not have permission to read, the default behavior is to deny access to the page and redirect to the error page.

There is a feature that changes this behavior and allows the use of optional transclusions.

This allows the creation of dynamic pages whose content changes according to the permissions of the user.

To use this feature, insert in LocalSettings.php:

$wgPageSecurityOptionalTransclusions = true;

With this option on, forbidden transclusions will be silently ignored and will not return any text.

Now you can create some templates and protect them using protection expressions. When used in a page, a template only will be shown if the user has read permission to it.

Verifying protection
You can verify that a page is protected by a security definition in two ways:
 * Create a notice in the security definition. This notice should be shown on the page footer (requires a patch on the skin template).
 * Open the rendered page HTML source code. The names of the security definitions applied to the page and to the pages it includes will be shown as meta tags identified by the name Page security definition.

Sysop access override
If sysops need special access to some pages, these permissions should be specified in the security definitions, like for any other user group.

If because of some configuration error the sysop is not able to edit the security definition page, an access override can be granted by inserting this line in LocalSettings.php:

$wgPageSecurityAllowSysop = true;

This override should be disabled once the configuration error is corrected.

Alternatives

 * Access
 * AccessControl Extension
 * CrudeProtection
 * DisallowAccessOnCategory
 * Hidden pages
 * How to Prevent Public Searching
 * Lockdown
 * NamespacePermissions Extension
 * Page access restriction with MediaWiki
 * Restrict pages under MediaWiki
 * Page by page access
 * Page-by-page authentication
 * PageProtection
 * PageProtectionPlus
 * Preventing Access
 * Setting user rights in MediaWiki
 * Simple Security
 * User access levels
 * User rights
 * Hierarchical Namespace Permission extension
 * Restricting Edit Access to User Pages

Feedback
Use the discussion page for feedback, questions, feature requests and bug reports.