Extension:PageSecurity

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
PageSecurity

Release status: beta

Implementation Tag, User rights
Description Restricts access to pages according to security definitions.
Author(s) Fernando Correia
Latest version 1.1.4 (2007-03-01)
MediaWiki 1.8, 1.9
License No license specified
Download PageSecurity.php

Translate the PageSecurity extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

Warning[edit | edit source]

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.

ALSO, it appears that this extension is no longer being maintained, and the current versions do not work after 1.9. IOW, you are on your own!

Introduction[edit | edit source]

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. 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)

NB: Please be aware that some of the command line tools maintenance tools will not work correctly with this extension. For example if you have locked down many of your pages and run refreshLinks.php all of those pages will be removed from the Categories they are in. (Further patches will be required to fix this)

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[edit | edit source]

  • 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[edit | edit source]

  • 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[edit | edit source]

  • 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[edit | edit source]

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

Configuration[edit | edit source]

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

Basic user rights[edit | edit source]

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

Insert in LocalSettings.php:

# require that users log in to read
$wgGroupPermissions['*']['read'] = false;
 
# require that users log in to edit
$wgGroupPermissions['*']['edit'] = false;
 
# allow these pages for anonymous users
$wgWhitelistRead = array( "Main Page", "Special:Userlogin", "-", "MediaWiki:Monobook.css" );
 
# remove the link to the talk page for non-logged in users
$wgShowIPinHeader = false;

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

Create user groups[edit | edit source]

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:

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

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[edit | edit source]

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[edit | edit source]

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:

# Disable feeds
$wgFeedClasses = array();

Disable cache[edit | edit source]

Insert in LocalSettings.php:

# Disable cache
$wgEnableParserCache = false;
$wgCachePages = false;

Activate the PageSecurity extension[edit | edit source]

Insert in LocalSettings.php:

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

Error page[edit | edit source]

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[edit | edit source]

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

Security definitions[edit | edit source]

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":

<security-definition name="Default"
  notice="This page can be read by all but only employees can edit it.">
  <allow action="read">all</allow>
  <allow action="write">Employees</allow>
</security-definition>
 
<security-definition name="Free access" base="Default"
  notice="This page can be read and written by all except guests.">
  <allow action="write">all</allow>
  <deny action="write">Guests</deny>
</security-definition>
 
<security-definition name="Official documentation"
  notice="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">
  <allow action="read">Employees, Customers</allow>
  <allow action="write">Documentation</allow>
</security-definition>

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.

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[edit | edit source]

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(<security-definition>, <subject area>, <pattern>)

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 #Security definitions).
  • 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", "{{Restricted}}");
 
// 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[edit | edit source]

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[edit | edit source]

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:

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

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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.

See Also[edit | edit source]

  • A modified version of PageSecurity which allows a user if he belongs to an allowed group... or not... If the variable $wgPageSecurityAllowGroupAccept is false or not set, then is the normal PageSecurity. If the variable is true then a user is allow if belongs to an allowed group. The modified code is at User:Fcarpani/PageSecurity Modified Version.

Alternatives[edit | edit source]

Feedback[edit | edit source]

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