Release status: stable
|Description||Automatically logs-in users if they are already authenticated by a remote source (e.g. environment variable
|Latest version||2.0.0 (2017-04-16)|
|License||GNU General Public License 2.0 or later|
You need a version of
Translate the Auth remoteuser extension if it is available at translatewiki.net
|Check usage and version matrix.|
|Open tasks · Report a bug|
Automatically logs-in users if they are already authenticated by an arbitrary remote source. The extension maps the given remote user name to an existing user name in the local wiki database (or creates it first if it has the permissions to do so). The external source takes total responsibility in authenticating that user.
This allows integration with the web server's built-in authentication system (for example via the
REMOTE_USER environment variable, which is set through HTTP-Auth, LDAP, CAS, PAM, etc.) or any other type of external authentication (SSL client auth, user accounts provided by different forum software, etc.).
- 1 Compatibility
- 2 Installation
- 3 Configuration
- 4 Configuring different remote sources
- 5 Support
Note: If you are using MediaWiki
1.26 or below, you need a version of Auth_remoteuser prior
2.0.0. See the legacy documentation in this case.
- Download and place the file(s) in a directory called
- Add the following code at the bottom of your LocalSettings.php:
wfLoadExtension( 'Auth_remoteuser' );
- Done - Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
To users running MediaWiki 1.26 or earlier:
The instructions above describe the new way of installing this extension using
wfLoadExtension() If you need to install this extension on these earlier versions (MediaWiki 1.26 and earlier), instead of
wfLoadExtension( 'Auth_remoteuser' );, you need to use:
Take account of MediaWikis global permissions for account creation (
autocreateaccount) inside your
LocalSettings.php. At least one of them must be
true for anonymous users to let this extension create accounts for users as of yet unknown to the wiki database. If you set this to
false, then automatic login works only for users who have a wiki account already.
// The extension can create accounts, because all anonymous users can. $wgGroupPermissions['*']['createaccount'] = true;
// If account creation by anonymous users is forbidden, then allow // it to be created automatically (by the extension). $wgGroupPermissions['*']['createaccount'] = false; $wgGroupPermissions['*']['autocreateaccount'] = true;
// Only login users automatically if known to the wiki already. $wgGroupPermissions['*']['createaccount'] = false; $wgGroupPermissions['*']['autocreateaccount'] = false;
Add some of the following global variables to your
LocalSettings.php to adjust the extensions behaviour to your specific needs. Default values for each global are marked with the "
// default" comment in the examples section.
|global||description & examples|
||Set the name(s) to use for mapping into the local wiki user database. This can either be a simple
||This extension comes with predefined remote user name filters (which are utilizing the provided hook). If you want to replace something, set an array of search and replacement patterns to the following configuration variable (Each pattern can be a regular expression in PCRE syntax too):
||If you want to prevent some names from beeing logged in automatically, blacklist them with the following filter. It accepts a list of names, where each name can also be a regular expression in PCRE syntax:
||The opposite of the
||When you have further user information available in your environment, which can be tied to a created user, for example email address or real name, then use one of the following configuration variables. Either
You can specify an anonymous function for the values too. These closures getting called when the actual value is needed, and not when it is declared inside your
Take the following as an example in which a cost-intensive function (in a timely manner) is getting executed only once per user and not on every request:
||You can replace urls in MediaWiki, if your remote source is better suited for handling specific behaviour. For example by default no automatically logged-in user is allowed to logout (because he will be logged-in automatically again with the next request). But maybe your remote source should handle that logout (so that with the next request there isn't a remote user name provided anymore to this extension). Set an appropriate url to one of the following keys of the associative array
||By default this extension mimics the behaviour of
||As an immutable SessionProvider (see
||If you are using other SessionProvider extensions besides this one, you have to specify their significance by using an ascending priority:
You can still use all legacy parameters from versions prior
v2.0.0, but their usage is deprecated in favour of the new parameters:
$wgAuthRemoteuserAuthz = true; /* Your own authorization test */ $wgAuthRemoteuserName = $_SERVER["AUTHENTICATE_CN"]; /* User's name */ $wgAuthRemoteuserMail = $_SERVER["AUTHENTICATE_MAIL"]; /* User's Mail */ $wgAuthRemoteuserNotify = false; /* Do not send mail notifications */ $wgAuthRemoteuserDomain = "NETBIOSDOMAIN"; /* Remove NETBIOSDOMAIN\ from the beginning or @NETBIOSDOMAIN at the end of a IWA username */ /* User's mail domain to append to the user name to make their email address */ $wgAuthRemoteuserMailDomain = "example.com";
When you need to process your remote user name before it can be used as an identifier into the wiki user list, for example to strip a Kerberos principal from the end, replacing invalid characters, or blacklisting some names, use the hook
AuthRemoteuserFilterUserName provided by this extension. Just have a look at MediaWikis Hook documentation on how to register additional functions to this hook. It provides as first parameter the remote user name by reference to the hook function. If the function returns
false, the remote user name will be ignored for automatic login. (See parameters
$wgAuthRemoteuserUserNameWhitelistFilter for predefined filters which utilizing this hook.)
Configuring different remote sources
REMOTE_USER environment variable
This environment variable can be set by many different authentication systems and the configuration of these is heavily dependent on which one you are using. You can always use
phpinfo(); to check the contents of
REMOTE_USER and to troubleshoot your setup. What follows are examples of different webserver environments and how to put a username into this environment variable.
Consult the Apache documentation for details. You can use
mod_auth_vas4 or any other authentication module that utilizes
REMOTE_USER. Once you have verified that the
REMOTE_USER environment variable is being set to the proper username, continue with installation/configuration of the extension. Some examples:
- For simple HTTP authentication add this
AuthType Digest AuthName Wiki AuthUserFile /etc/passwd-apache Require valid-user
REMOTE_USERenvironment variable is getting evaluated by default from the extension, so the following code is all you need in your
wfLoadExtension( 'Auth_remoteuser' );
- Setup HTTP SPNEGO with Vintella/Quest Authentication Services for your heterogeneous network, using
AuthType VAS4 AuthVasRemoteUserMap default AuthVasUseBasic On AuthName Wiki Require valid-user
- Now the
REMOTE_USERenvironment variable contains the full principal name, so remove the realm from the username inside your
wfLoadExtension( 'Auth_remoteuser' ); $wgAuthRemoteuserUserNameReplaceFilter = [ '@INTRA.EXAMPLE.COM$' => '' ];
Depending on your version of Internet Information Services (IIS) Manager, your navigation may be slightly different. The instructions below are specified for a corporate server running IIS v7.5 on Windows Server 2008 R2 Enterprise. (Trust me, I wanted Linux and Apache but IT wont allow it)
To enable simple authentication navigate to the following paths.
- (Server Name) > Sites > Default Web Site
- From "Features View" double click, "Authentication"
- Disable - "Anonymous Authentication"
- Enable - "Windows Authentication" (HTTP 401 Challenge)
This extension gets managed as a project on Phabricator. There you can see a list of all known and still open issues. If there is no open task related to the problem/error you've encountered, then have a look on howto report errors.
Regarding versions of this extension prior
v2.0.0 you may find a suitable solution for your problem by having a look at
Read the MediaWiki manual on debugging or take the following as a start:
- Enable logging by setting the
LocalSettings.phpto a file to which your webserver has write access to.
- Request your MediaWiki installation like you did when the error occured. This extension logs all its output to the
[session]channel into your log file.
- Inspect the log file and search for all lines starting with
- Decide if you can fix the error by yourself or if it is related to how this extension works. If so, then have a look on howto report errors.
Assemble relevant debugging information (relevant in terms of others can reproduce the error) and:
- Either read MediaWikis howto on reporting bugs, or
- create a new task on this extensions Phabricator project (if you have a Phabricator account), or
- write an email to members of the Phabricator project, or
- use this extensions talk page.
You're welcome to enhance this extension. Read How_to_become_a_MediaWiki_hacker, grab one of the open issues from the Phabricator project (or create a new task) and upload your patch to this extensions Gerrit project. There you can also see:
- a list of current extension maintainers with write access (if you have a Gerrit account),
- a list of uploaded patch sets.
Just use the same workflow as with error reporting.