Auth_remoteuser
Auth_remoteuser is an extension for MediaWiki 1.27 and up which logs-in
users into mediawiki automatically if they are already authenticated by
a remote source. This can be anything ranging from webserver environment
variables to request headers to arbitrary external sources if at least
the remote user name maps to an existing user name in the local wiki
database (or it can be created if the extension has the permissions to
do so). The external source takes total responsibility in authenticating
an authorized user., (*1)
Because it is implemented as a SessionProvider in MediaWikis AuthManager
stack, which was introduced with MediaWiki 1.27, you need a version of
Auth_remoteuser below 2.0.0 to use this extension in MediaWiki 1.26 and
below., (*2)
Requirements
Installation
Either copy this extension directory Auth_remoteuser/ into your
mediawiki extension folder extensions/ or, when installing with
Composer, add an appropriate required package link to your
composer.local.json file:, (*3)
"require": { "mediawiki/auth-remoteuser": "~2" }
Then, enable the extension in MediaWiki by adding the following to your
global configuration file LocalSettings.php:, (*4)
wfLoadExtension( 'Auth_remoteuser' );
Take account of MediaWikis global permissions for account creation
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:, (*5)
$wgGroupPermissions['*']['createaccount'] = true;
// If account creation by anonymous users is forbidden, then allow
// it to be created automatically.
$wgGroupPermissions['*']['createaccount'] = false;
$wgGroupPermissions['*']['autocreateaccount'] = true;
// Only login users automatically if known to the wiki already.
$wgGroupPermissions['*']['createaccount'] = false;
$wgGroupPermissions['*']['autocreateaccount'] = false;
Configuration
You can adjust the behaviour of the extension to suit your needs by
using a set of global configuration variables all starting with
$wgAuthRemoteuser. Just add them to your LocalSettings.php. Default
values, which you don't have to set explicitly are marked with the
// default comment., (*6)
-
Set the name(s) to use for mapping into the local wiki user database.
This can either be a simple string, a closure or a mixed array of
strings and/or closures. If the value is null, the extension
defaults to using the environment variables REMOTE_USER and
REDIRECT_REMOTE_USER. The first name name in the given list, which
can be used as a valid MediaWiki user name, will be taken for login
(either by login to an existing wiki account or by creating first).
Examples:, (*7)
$wgAuthRemoteuserUserName = null; // default
// Same behaviour as default `null`.
$wgAuthRemoteuserUserName = [
$_SERVER[ 'REMOTE_USER' ],
$_SERVER[ 'REDIRECT_REMOTE_USER' ]
];
// Another remote source for user name(s).
$wgAuthRemoteuserUserName = $_SERVER[ 'LOGON_USER' ];
$wgAuthRemoteuserUserName = ""; // Will evaluate to nothing.
$wgAuthRemoteuserUserName = []; // Will evaluate to nothing.
// This is not advised, because it will evaluate every visitor
// to the same wiki user 'Everybody'.
$wgAuthRemoteuserUserName = "Everybody";
// Create a closure instead of providing strings directly.
$wgAuthRemoteuserUserName = function() {
$credentials = explode( ':',$_SERVER['HTTP_AUTHORIZATION']);
$username = $credentials[0];
$password = $credentials[1];
return MyOwnAuthorizer::authenticate( $username, $password )
? $username : "";
};
-
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., (*8)
-
This extension comes with predefined remote user name filters (which
are using the hook mentioned above). 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):, (*9)
$wgAuthRemoteuserUserNameReplaceFilter = null; // default
$wgAuthRemoteuserUserNameReplaceFilter = [
'_' => ' ', // replace underscores with
// spaces
'@INTRA.EXAMPLE.COM$' => '', // strip Kerberos principal
// from back
'^domain\\' => '', // strip NTLM domain from front
'johndoe' => 'Admin', // rewrite user johndoe
'/JaNeDoE/i' => 'Admin', // rewrite all case-insensitive
// versions of janedoe
'^(.*)$' => 'auto_$1', // prepend string 'auto_'
'^cn=(.*),dc=com$' => '$1', // get nested user name
'^([^,]*),(.*)$' => '$2 $1' // reorder names
];
-
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:, (*10)
$wgAuthRemoteuserUserNameBlacklistFilter = null; // default
$wgAuthRemoteuserUserNameBlacklistFilter = [
'johndoe',
'janedoe',
'/john/i', // matches all case-insensitive versions of john
'^f_' // matches all users starting wit 'f_'
];
-
The opposite of the UserNameBlacklistFilter can be achieved by using
the following filter, which permits the automatic login instead of
preventing it:, (*11)
$wgAuthRemoteuserUserNameWhitelistFilter = null; // default
$wgAuthRemoteuserUserNameWhitelistFilter = [
'john',
'jane'
];
-
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
UserPrefs or UserPrefsForced, which applies them to new users only
or force them by applying them on each request. This can be useful if
you don't want the user to change this preference inside MediaWiki
(for example your company email address given by a remote source).
They are expecting an array of key value pairs of which 'realname' and
'email' corresponds to the new users real name and email address. Any
further key value pair specified gets mapped to a user preference of
the same name. But take note of MediaWikis $wgDefaultUserOptions and
$wgHiddenPrefsfor declaring user preference options. In most cases
these globals are better suited for a definition of a default value
and disabling their modifiability:, (*12)
$wgAuthRemoteuserUserPrefs = null; // default
$wgAuthRemoteuserUserPrefsForced = null; // default
$wgAuthRemoteuserUserPrefs = [
'realname' => $_SERVER[ 'AUTHENTICATE_DISPLAYNAME' ],
'language' => 'en',
'disablemail' => 0
];
// Users email address should not be changed inside MediaWiki.
$wgAuthRemoteuserUserPrefsForced = [
'email' => $_SERVER[ 'AUTHENTICATE_MAIL' ]
];
// Instead use MediaWiki global for the preference option.
$wgDefaultUserOptions[ 'disablemail' ] = 0;
// And disable it from being changed by the user.
$wgHiddenPrefs[] = 'disablemail';
// But change it depending on type of remote user (uses the
// closure feature described below). For example if there are
// guest accounts identified by a leading 'g_' existing at your
// remote source, which have no valid email address, then
// disable the option specifically for these type of accounts.
$wgAuthRemoteuserUserPrefsForced = [
'disablemail' => function ( $metadata ) {
$name = $metadata[ 'remoteUserName' ];
return ( preg_match( '/^g_/', $name ) ) ? 1 : 0;
}
];
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 LocalSettings.php. The first parameter
given to the function is an associative array with the following keys:, (*13)
-
userId - id of user in local wiki database or 0 if new/anonymous
-
remoteUserName - value as given by the environment
-
filteredUserName - after running hook for filtering user names
-
canonicalUserName - representation in the local wiki database
-
canonicalUserNameUsed - the user name used for the current session
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:, (*14)
$wgAuthRemoteuserUserPrefs = [
'email' => function( $metadata ) use ( $rpc ) {
$name = $metadata[ 'remoteUserName' ];
// costly remote procedure call to get email address
return $rpc->query( 'email', $name );
}
];
-
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 wgAuthRemoteuserUserUrls:, (*15)
-
logout - Provide a redirect url for the user logout. Depending on
your other extension configuration settings this will either replace
the link of the logout button in the user's personal url bar or
redirect after a call to the special page Special:UserLogout.
Accepts a string or a closure. If of type closure, then it should
return a string with a valid url (either external or internal). The
closure gets as first parameter the same array as closures for the
user preferences (see description there).
Examples:, (*16)
$wgAuthRemoteuserUserUrls = null; // default
// Redirect to company domain controller host for logout.
$wgAuthRemoteuserUserUrls = [
'logout' => function( $metadata ) {
$user = $metadata[ 'remoteUserName' ];
return 'https://company.example.com/?logout=' . $user;
}
];
// Redirect to user login page instead of default logout page.
// This is the default behaviour if user switching is allowed.
$wgAuthRemoteuserUserUrls = [
'logout' => function( $metadata ) {
return 'Special:UserLogin';
}
];
-
By default this extension mimics the behaviour of Auth_remoteuser
versions prior 2.0.0, which prohibits using another local user then
the one identified by the remote source. You can change this behaviour
with the following configuration:, (*17)
$wgAuthRemoteuserAllowUserSwitch = false; // default
$wgAuthRemoteuserAllowUserSwitch = true;
-
As an immutable SessionProvider (see AllowUserSwitch config above)
all special pages and login/logout links for authentication aren't
needed anymore by the identified user. If you still want them to be
shown, for example if you are using other session providers besides
this one, then set the following accordingly:, (*18)
$wgAuthRemoteuserRemoveAuthPagesAndLinks = true; // default
$wgAuthRemoteuserRemoveAuthPagesAndLinks = false;
-
If you are using other SessionProvider extensions besides this one,
you have to specify their significance by using an ascending priority:, (*19)
$wgAuthRemoteuserPriority = 50; // default
$wgAuthRemoteuserPriority = SessionInfo::MAX_PRIORITY;
Upgrade
This extension doesn't use any database entries, therefore you don't
need that extension to be enabled while upgrading. Just disable it and
after you have upgraded your wiki, reenable this extension., (*20)
Upgrading from versions prior 2.0.0
All legacy configuration parameters are still fully supported. You don't
have to rewrite your old LocalSettings.php settings. But to assist you
in transitioning of old configuration parameters to new ones, the
following list can guide you:, (*21)
-
$wgAuthRemoteuserAuthz - This parameter has no equivalent new
parameter, because you can achive the same with not loading the
extension at all.
-
$wgAuthRemoteuserName - Superseded by $wgRemoteuserUserPrefs.
-
$wgAuthRemoteuserMail - Superseded by $wgRemoteuserUserPrefs.
-
$wgAuthRemoteuserNotify - Superseded by $wgRemoteuserUserPrefs.
-
$wgAuthRemoteuserDomain - Superseded by
$wgRemoteuserUserNameReplaceFilter.
-
$wgAuthRemoteuserMailDomain - Superseded by $wgRemoteuserUserPrefs.
Additional notes
For a complete list of authors and any further documentation see the
file extension.json or the Special:Version page on your wiki
installation after you have enabled this extension., (*22)
For the license see the file COPYING., (*23)
Wallogit.com
