How to Set Up and Manage User Groups in MediaWiki

Why User Groups Matter

MediaWiki’s permission system is built around user groups. A group is simply a label attached to a user account; the label grants a predefined set of rights (read, edit, block, etc.). By combining groups you can give a user exactly the capabilities you need while keeping the rest of the wiki safe.

Default Groups and Their Rights

When you install MediaWiki you get a handful of pre‑configured groups:

• * – all visitors, including anonymous users. By default they can read, create accounts and (on an open wiki) edit.
• user – every registered account. In addition to the “*” rights they inherit the read and edit rights.
• autoconfirmed – users who have met the age and edit‑count thresholds defined by $wgAutoConfirmAge and $wgAutoConfirmCount. This group can bypass some rate limits and edit semi‑protected pages.
• bot – accounts that run automated scripts. Their edits are hidden from recent‑change feeds.
• sysop – administrators (sometimes called “sysops”). They can delete, block, protect, and perform most high‑level actions.
• bureaucrat – users who can change other users’ groups via the Special:UserRights interface.

All of these groups are listed on the special page Special:ListGroupRights. The page shows each right’s description and the groups that own it, which is handy when you are planning a custom group.

Viewing and Editing Group Membership

The primary UI for managing groups is Special:UserRights. Only users with the userrights right (by default, bureaucrats) can see the page. To add or remove a user from a group:

1. Enter the username in the text box and press “Load user groups”.
2. Check or uncheck the boxes next to the groups you want to modify.
3. Optionally add a reason – it will appear in the user‑rights log.
4. Click “Save user groups”.

Changes are recorded in the “User rights log” (accessible via Special:Log) so you can audit who granted which rights and when.

Creating Custom Groups in LocalSettings.php

For most wikis a custom group is the cleanest way to give a specific set of permissions to a subset of users. A group is created the moment you assign it a right in $wgGroupPermissions. Example:

# Give a new group called "content‑reviewer" the ability to
# view semi‑protected pages and edit them without the "autoconfirmed"
# restriction.
$wgGroupPermissions['content-reviewer']['editsemiprotected'] = true;
$wgGroupPermissions['content-reviewer']['read'] = true;

After you add the snippet to LocalSettings.php the group appears on Special:UserRights and can be assigned like any built‑in group.

Best practice: use lower‑case letters, hyphens or underscores, and avoid spaces in the group name. The name you use in the array is the internal key; the human‑readable name is defined on three wiki pages:

• MediaWiki:Group‑group‑name – the label shown in the UI.
• MediaWiki:Group‑group‑name-member – the label for a single member (e.g. “reviewer”).
• MediaWiki:Grouppage‑group‑name – a wiki page that can contain a description of the group’s purpose.

Creating those pages makes the group feel native to the wiki and helps other editors understand its role.

Fine‑Tuning Permissions

The $wgGroupPermissions array works like a matrix: each group can be granted (true) or denied (false) a specific right. Rights are additive – if a user belongs to two groups, they receive the union of both groups’ rights. A denial in one group does not override a grant in another.

Typical custom‑group patterns

Temporary moderators: a group with short‑lived block rights.

$wgGroupPermissions['temp-mod']['block']n$wgGroupPermissions['temp-mod']['editprotected'] = true;

Limited uploaders: users who may upload files but cannot overwrite existing ones.

$wgGroupPermissions['uploader']['upload'] = true;
$wgGroupPermissions['uploader']['reupload'] = false;

Read‑only editors: users who can add content but never delete.

$wgGroupPermissions['readonly']['edit'] = true;
$wgGroupPermissions['readonly']['delete'] = false;

Group Expiry

MediaWiki (since 1.29) supports expiring group memberships. When you edit a user via Special:UserRights you can set an “Expires” value – either a relative period (e.g. “10 weeks”) or an absolute timestamp (“2025‑12‑31”). After the expiry the user automatically loses that group. This is useful for trial moderators or seasonal contributors.

Automating Group Assignment

There are two built‑in mechanisms to promote users automatically:

Bot or script assignment using the API or the maintenance script createAndPromote.php. The script can be run from the command line:

php maintenance/run.php createAndPromote.php UserName --addgroup=project-member

Note that the script only adds groups; removal must be done manually or via direct database edits.

Autopromotion via $wgAutopromote. You can define conditions based on account age, edit count, email confirmation, etc.

$wgAutopromote['trusted'] = APCOND_EDITCOUNT >= 500 && APCOND_AGE >= 90; // 90 days, 500 edits

This creates a group called trusted and adds every user who meets the criteria.

Using the API for Group Management

When you need to manage groups from a bot, extension, or external tool, the MediaWiki API provides the userrights action. Example request (POST):

action=userrights&user=JaneDoe&add=content-reviewer&token=+\

Remember to fetch a CSRF token first (action=query&meta=tokens&type=csrf). The API respects the same permission checks as the UI – the calling user must have the userrights right.

Extension‑Based Group Management

If you prefer a UI that lets you create, rename, or delete groups without editing LocalSettings.php, the Extension:UserGroups adds a special page Special:UserGroups. The extension is unmaintained but still functional on recent MediaWiki releases. It introduces a new right modifygroups (default only for bureaucrats). After enabling the extension:

wfLoadExtension( 'UserGroups' );
$wgGroupPermissions['sysop']['modifygroups'] = true; // optional: let sysops manage groups

From Special:UserGroups you can create a group, assign rights, and delete groups. The extension does not replace $wgAddGroups and $wgRemoveGroups – those still need to be defined in LocalSettings.php if you want to limit which groups a user may add or remove.

Security Considerations

• Never grant userrights to untrusted users. That right lets a user modify any other user’s groups.
• Test new permissions on a sandbox wiki first. Adding a right like editinterface to a group you didn’t intend to give site‑wide CSS/JS rights can be disastrous.
• Use group expiry for temporary privileges. It reduces the risk of forgotten moderator accounts.
• Keep the list of rights up to date. MediaWiki adds new rights over time; review Special:ListGroupRights after each upgrade.

Lock down $wgAddGroups and $wgRemoveGroups if you use custom groups. By default any bureaucrat can add any group; you can restrict it, e.g.:

$wgAddGroups['bureaucrat'] = ['project-member']; // bureaucrats can only add this group
$wgRemoveGroups['bureaucrat'] = ['project-member'];

Common Pitfalls and How to Avoid Them

• Spaces in group names. MediaWiki stores the key without spaces; using a space in the UI will silently create a different key. Stick to hyphens or underscores.
• Removing a built‑in group. Deleting sysop or bureaucrat can lock you out. If you really need to, unset all related configuration arrays ($wgGroupPermissions, $wgAddGroups, etc.) after extensions have loaded.
• Conflicting rights. If one group denies a right (false) and another grants it (true), the grant wins. Only use explicit false when you really need to block a right for a specific group that would otherwise inherit it.
• Missing UI messages. If you create a group but forget the three MediaWiki:Group‑… pages, the UI will show raw keys like “project‑member”. Create those pages to give a friendly name.

Step‑by‑Step Checklist

1. Identify the exact set of rights you need (consult Special:ListGroupRights).
2. Decide whether a custom group or an existing one fits the need.
3. If custom, add the required $wgGroupPermissions entries to LocalSettings.php.
4. Create the three MediaWiki:Group‑… pages for a readable label.
5. Use to assign users, optionally setting an expiry.
6. If you want automatic promotion, configure $wgAutopromote.
7. Restrict who can add/remove the new group via $wgAddGroups / $wgRemoveGroups.
8. Test the new permissions on a test account before giving them to many users.
9. Document the group purpose on its Grouppage‑… wiki page.
10. Monitor the “User rights log” for unexpected changes.

Conclusion

Managing user groups in MediaWiki is a blend of UI actions and PHP configuration. The built‑in groups cover most day‑to‑day scenarios, but the $wgGroupPermissions matrix lets you craft precise permission sets for any workflow – from seasonal moderators to content‑review teams. By following the checklist above, using expiry where appropriate, and keeping the permission matrix under version control, you can maintain a secure, flexible wiki that scales with your community.