Jump to content

Extension:MediaWikiAuth

From mediawiki.org
MediaWiki extensions manual
MediaWikiAuth
Release status: stable
Implementation User identity
Description Transparently imports users from another wiki
Author(s)
Latest version 1.3.1 (2020-05-29)
Compatibility policy Master maintains backward compatibility.
MediaWiki 1.31+ (for remote wikis running 1.19+)
License GNU General Public License 2.0 or later
Download Download latest version
  • $wgMediaWikiAuthImportOptions
  • $wgMediaWikiAuthSkipOptions
  • $wgMediaWikiAuthReattributeEdits
  • $wgMediaWikiAuthAllowPasswordChange
  • $wgMediaWikiAuthImportWatchlist
  • $wgMediaWikiAuthDisableAccountCreation
  • $wgMediaWikiAuthImportGroups
  • $wgMediaWikiAuthApiUrl
  • mwa-createlocalaccount

The MediaWikiAuth extension transparently logs a user in to a remote wiki, importing the user's account and preferences to the local wiki.

What can this extension do?

[edit]

This extension uses the MediaWiki API and AuthManager framework to direct login requests with no local account to a remote wiki. The account and its preferences are imported, so the remote login only has be done once.

This extension is useful for moving a community from another wiki when you do not have access to the user account database. From a user perspective, it's like they already had an account on the local wiki.

Usage

[edit]

Install MediaWikiAuth as specified below, set $wgMediaWikiAuthApiUrl for the remote wiki, and login using an account on the remote wiki which is not currently present on the local wiki. Preferences and watchlists will be imported; watchlists are imported via the job queue so for large watchlists it may take a while for them to be fully imported. Additionally, existing imported edits can be reattributed to the imported user should the username match, which causes those edits to properly show up on that user's Contributions page. This reattribution also takes place via the job queue to avoid negatively impacting performance.

MediaWikiAuth does not import revisions or uploads, you will need to import those separately. If you import them before enabling this extension, those imported revisions will be reattributed to the correct local user whenever they create their account. If you import after, the importer is usually smart enough to reattribute revisions on its own. In the event either process fails, a reattributeImportedEdits.php maintenance script is provided which can be manually run to force edit reattribution.

If you additionally imported remote users before enabling this extension, ensure that any users you wish enable remote sign-on with have invalid password hashes in the user table, then set $wgMediaWikiAuthDisableAccountCreation = true; in your LocalSettings.php. More information on this option is below.

Installation

[edit]
  • Download and place the file(s) in a directory called MediaWikiAuth in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php file:
    wfLoadExtension( 'MediaWikiAuth' );
    // set this to the URL of the remote wiki's api.php
    $wgMediaWikiAuthApiUrl = 'https://example.com/w/api.php';
    // Let sysops manually create local accounts, even if they exist remotely
    $wgGroupPermissions['sysop']['mwa-createlocalaccount'] = true;
    
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration and permissions

[edit]

The following are optional configurations you can apply:

$wgMediaWikiAuthAllowPasswordChange (boolean, default true)
If true, after importing their account the user will be prompted to optionally change their password (or choose a Skip button to keep the same password).
$wgMediaWikiAuthImportGroups (boolean or array of strings, default true)
This configuration controls which local user groups are assigned to the user. If true (the default), all group memberships that the user had on the remote wiki are imported to the local wiki, provided groups of the same name exist locally. If false, no group memberships are imported. If an array, the configuration lists which groups to copy over; only those listed are imported. In either case, implicit groups cannot be imported, and any group expiration data is kept intact.
$wgMediaWikiAuthDisableAccountCreation (boolean, default false)
If true, MediaWikiAuth assumes that all relevant users have already been created locally, but with invalid password hashes. This is useful if you only want to import some subset of all of the users on the remote wiki, such as anyone that has edited remotely. If true, MediaWikiAuth will detect the invalid password and attempt to auth against the remote wiki with the user's given password. If successful, the user will be required to change their local password so that they may log in normally in the future.
When operating in this mode, watchlist, group imports, and edit reattribution do not happen. Those settings are ignored.
$wgMediaWikiAuthImportWatchlist (boolean, default true)
If true, watchlists will be imported via the job queue. If false, watchlists will not be imported. Enabling this will cause additional requests to the remote API. Should the remote server be exceptionally slow, these additional requests may time out the user import process. In this case, you will want to disable this setting.
$wgMediaWikiAuthReattributeEdits (boolean, default true)
If true, existing imported edits which match the newly-created account's username will be reattributed via the job queue so they properly show in that user's Contributions page. If false, no reattribution occurs.

The following group permissions have been added. By default, they are not granted to anyone (you will need to assign them yourself with $wgGroupPermissions):

mwa-createlocalaccount
A group with this permission is allowed to create a local account manually via Special:CreateAccount even if a user with the same name exists on the external wiki. By default, if a username exists on the external wiki, it is impossible to manually create a local account without importing it (even if it is blocked, locked, etc.). It is recommended to assign this to an administrators group, such as sysop.

Maintenance scripts

[edit]

The reattributeImportedEdits.php maintenance script may be found in the maintenance directory of this extension. In addition to common maintenance script options, it takes a --user option, which can be used to specify a single username to reattribute edits for. If --user is not specified, it will run on every user. This script looks for revisions and uploads which have a username matching an existing wiki user, but a user id of 0 (indicating anonymous users). This is the case when importing revisions or uploads when a local user account matching the username does not exist.

See also

[edit]
  • ImportUsers extension
  • WSOAuth extension for authenticating against a remote wiki where an account does not need to be imported locally
  • StubUserWikiAuth - based on the original version of MediaWikiAuth
  • MigrateUserAccount extension for migrating users from an external wiki without logging in directly