MediaWiki

Extension:Auth remoteuser

Translate this page
Languages:
Not to be confused with Extension:AuthRemoteUser.
MediaWiki extensions manual
Auth_remoteuser
Release status: stable
Implementation User identity , Hook
Description Automatically logs-in users if they are already authenticated by a remote source (e.g. environment variable REMOTE_USER).
Author(s)
Latest version 2.1.1
MediaWiki >= 1.39.0
PHP 5.4+
Database changes No
Composer mediawiki/auth-remoteuser
License GNU General Public License 2.0 or later
Download
Download extension
Git [?]:

README
Parameters

  • $wgAuthRemoteuserUserName
  • $wgAuthRemoteuserUserNameReplaceFilter
  • $wgAuthRemoteuserUserNameBlacklistFilter
  • $wgAuthRemoteuserUserNameWhitelistFilter
  • $wgAuthRemoteuserUserPrefs
  • $wgAuthRemoteuserUserPrefsForced
  • $wgAuthRemoteuserUserUrls
  • $wgAuthRemoteuserAllowUserSwitch
  • $wgAuthRemoteuserRemoveAuthPagesAndLinks
  • $wgAuthRemoteuserPriority

Legacy parameters:

  • $wgAuth
  • $wgAuthRemoteuserAuthz
  • $wgAuthRemoteuserDomain
  • $wgAuthRemoteuserName
  • $wgAuthRemoteuserMail
  • $wgAuthRemoteuserNotify
  • $wgAuthRemoteuserDomain
  • $wgAuthRemoteuserMailDomain
Hooks used
Hooks provided
Quarterly downloads 225 (Ranked 28th)
Translate the Auth remoteuser extension
Issues Open tasks · Report a bug

The Auth remoteuser extension 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[1], LDAP[2], CAS[3], PAM[4], etc.) or any other type of external authentication (SSL[5] client auth, user accounts provided by different forum software, etc.).

Installation

  • Download and move the extracted Auth_remoteuser folder to your extensions/ directory.
    Developers and code contributors should install the extension from Git instead, using:cd extensions/
    git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Auth_remoteuser
  • Add the following code at the bottom of your LocalSettings.php file: 
    wfLoadExtension( 'Auth_remoteuser' );
  •   Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Configuration

Take account of MediaWikis global permissions for account creation (createaccount or 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.

Examples
  1. // The extension can create accounts, because all anonymous users can.
$wgGroupPermissions['*']['createaccount'] = true;

  2. // If account creation by anonymous users is forbidden, then allow it to be created automatically (by the extension).
$wgGroupPermissions['*']['createaccount'] = false;
$wgGroupPermissions['*']['autocreateaccount'] = true;

  3. // Only login users automatically if known to the wiki already.
$wgGroupPermissions['*']['createaccount'] = false;
$wgGroupPermissions['*']['autocreateaccount'] = false;

Parameters

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
$wgAuthRemoteuserUserName Set the name(s) to use for mapping into the local wiki user database. This can either be a simple string, a Closure[6] or a mixed array of strings and/or Closure. If the value is null, the extension defaults to using the environment variables REMOTE_USER and REDIRECT_REMOTE_USER. The first 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): 
  1. $wgAuthRemoteuserUserName = null; // default

  2. // Same behaviour as default `null`.
$wgAuthRemoteuserUserName = [
    $_SERVER[ 'REMOTE_USER' ],
    $_SERVER[ 'REDIRECT_REMOTE_USER' ]
];

  3. // Another remote source for user name(s).
$wgAuthRemoteuserUserName = getenv( 'LOGON_USER' );

  4. $wgAuthRemoteuserUserName = ""; // Will evaluate to nothing.

  5. // This is not advised, because it will evaluate every visitor
// to the same wiki user 'Everybody'.
$wgAuthRemoteuserUserName = "Everybody";

  6. // 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 : '';
};

  7. // When using the VisualEditor extension create a specific parsoid user for
// locked down wikis (no anonymous read permission), when Parsoid is running
// on localhost.
$wgAuthRemoteuserUserName = [
    $_SERVER[ 'REMOTE_USER' ],
    $_SERVER[ 'REDIRECT_REMOTE_USER' ],
    $_SERVER[ 'REMOTE_ADDR' ] == '127.0.0.1' ? 'parsoid' : ''
];
$wgAuthRemoteuserUserNameReplaceFilter 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[7] syntax too): 
  1. $wgAuthRemoteuserUserNameReplaceFilter = null; // default

  2. $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 name parts
];
$wgAuthRemoteuserUserNameBlacklistFilter If you want to prevent some names from being 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: 
  1. $wgAuthRemoteuserUserNameBlacklistFilter = null; // default

  2. $wgAuthRemoteuserUserNameBlacklistFilter = [
    'johndoe',
    'janedoe',
    '/john/i', // matches all case-insensitive versions of john
    '^f_'      // matches all users starting wit 'f_'
];
$wgAuthRemoteuserUserNameWhitelistFilter The opposite of the UserNameBlacklistFilter can be achieved by using the following filter, which permits the automatic login instead of preventing it: 
  1. $wgAuthRemoteuserUserNameWhitelistFilter = null; // default

  2. $wgAuthRemoteuserUserNameWhitelistFilter = [
    'john',
    'jane'
];
$wgAuthRemoteuserUserPrefs

$wgAuthRemoteuserUserPrefsForced

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 $wgHiddenPrefs for declaring user preference options. In most cases these globals are better suited for a definition of a default value and disabling their modifiability: 
  1. $wgAuthRemoteuserUserPrefs = null;       // default
$wgAuthRemoteuserUserPrefsForced = null; // default

  2. $wgAuthRemoteuserUserPrefs = [
    'realname' => $_SERVER[ 'AUTHENTICATE_DISPLAYNAME' ],
    'language' => 'en',
    'disablemail' => 0
];
// Users email address should not be changed inside MediaWiki.
$wgAuthRemoteuserUserPrefsForced = [
    'email' => $_SERVER[ 'AUTHENTICATE_MAIL' ]
];

  3. // 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:

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

  1. $wgAuthRemoteuserUserPrefs = [
    'email' => function( $metadata ) use ( $rpc ) {
        $name = $metadata[ 'remoteUserName' ];
        // costly remote procedure call to get email address
        return $rpc->query( 'email', $name );
    }
];
$wgAuthRemoteuserUserUrls 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:
  • 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).
  1. $wgAuthRemoteuserUserUrls = null; // default

  2. // Redirect to user login page instead of default logout page.
// This is the default behaviour if user switching is allowed.
$wgAuthRemoteuserUserUrls = [
    'logout' => 'Special:UserLogin'
];

  3. // Redirect to company domain controller host for logout.
$wgAuthRemoteuserUserUrls = [
    'logout' => function( $metadata ) {
        $user = $metadata[ 'remoteUserName' ];
        return 'https://company.example.com/?logout=' . $user;
    }
];
$wgAuthRemoteuserAllowUserSwitch By default this extension mimics the behaviour of Auth_remoteuser versions prior v2.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: 
  1. $wgAuthRemoteuserAllowUserSwitch = false; // default

  2. $wgAuthRemoteuserAllowUserSwitch = true;
$wgAuthRemoteuserRemoveAuthPagesAndLinks 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: 
  1. $wgAuthRemoteuserRemoveAuthPagesAndLinks = true; // default

  2. $wgAuthRemoteuserRemoveAuthPagesAndLinks = false;
$wgAuthRemoteuserPriority If you are using other SessionProvider extensions besides this one, you have to specify their significance by using an ascending priority: 
  1. $wgAuthRemoteuserPriority = 50; // default

  2. $wgAuthRemoteuserPriority = SessionInfo::MAX_PRIORITY;

Legacy parameters

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

Provided hooks

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 $wgAuthRemoteuserUserNameReplaceFilter, $wgAuthRemoteuserUserNameBlacklistFilter or $wgAuthRemoteuserUserNameWhitelistFilter for predefined filters which utilizing this hook.)

Configuring different remote sources

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

Apache

Consult the Apache documentation for details. You can use mod_auth_ldap, mod_auth_cas, mod_auth_pam, mod_auth_kerb, 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 .htaccess:
AuthType Digest
AuthName Wiki
AuthUserFile /etc/passwd-apache
Require valid-user
The REMOTE_USER environment variable is getting evaluated by default from the extension, so the following code is all you need in your LocalSettings.php: 
wfLoadExtension( 'Auth_remoteuser' );

AuthType VAS4
AuthVasRemoteUserMap default
AuthVasUseBasic On
AuthName Wiki
Require valid-user
Now the REMOTE_USER environment variable contains the full principal name, so remove the realm from the username inside your LocalSettings.php with: 
wfLoadExtension( 'Auth_remoteuser' );
$wgAuthRemoteuserUserNameReplaceFilter = [
    '@INTRA.EXAMPLE.COM$' => ''
];

Kerberos SSO AD

Prerequisites:

  1. mod_auth_kerb
  2. mod_auth_ldap
  3. mod_authnz_ldap

To install & enable them in Devuan: 

apt install libapache2-mod-auth-kerb
a2enmod authnz_ldap

Configure Kerberos in the OS (long story short):

  1. Join to AD domain:
    1. realm join corp.ds.company.net -U domain_user_with_rights_to_join --computer-ou="use dsquery computer in windows cmd domain joined machine to get the value" --verbose
  2. Generate keytab on Windows AD server cmd:
    1. ktpass -princ HTTP/en.mediawiki.company.net@CORP.DS.COMPANY.NET -mapuser mediawiki_windows_domain_user@CORP.DS.COMPANY.NET -pass mediawiki_windows_domain_user_secret_password -crypto all -ptype KRB5_NT_PRINCIPAL -out C:\Temp\en-mediawiki.keytab
    2. setspn -A HTTP/en.mediawiki.company.net@CORP.DS.COMPANY.NET mediawiki_windows_domain_user@CORP.DS.COMPANY.NET

Apache con file: 

AuthType Kerberos
Krb5Keytab /path/to/your/keytab_file.keytab
KrbServiceName Any
KrbLocalUserMapping On
AuthLDAPBindDN "user_name_to_authenticate_to_LDAP_server"
AuthLDAPBindPassword "password_for_the_user_from_above"
AuthLDAPURL "http://ldap_server_url/DC=CORP,DC=DS,DC=COMPANY,DC=NET?sAMAccountName,mail,displayName?sub?(objectClass=*)"
Require ldap-attribute attribute="value"

It is required to use LDAP authorization together with Kerberos SSO[9] if you want to get user information (email, real name) from AD.

The info from LDAP must be published to AUTHORIZE_ environment variables, so make sure you use it, not AUTHENTICATE_ in LocalSettings.php.

Using ldap-group did not publish environment variables for me, using ldap-attribute did (a bug in apache?).

IIS

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.

  1. IIS
  2. (Server Name) > Sites > Default Web Site
  3. From "Features View" double click, "Authentication"
  4. Disable — "Anonymous Authentication"
  5. Enable — "Windows Authentication" (HTTP 401 Challenge)

Support

Known issues

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.

Howto debug

Read the MediaWiki manual on debugging or take the following as a start:

  1. Enable logging by setting the $wgDebugLogFile inside your LocalSettings.php to a file to which your webserver has write access to.
  2. Request your MediaWiki installation like you did when the error occurred. This extension logs all its output to the [session] channel into your log file.
  3. Inspect the log file and search for all lines starting with [session].
  4. 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.

Report errors

Assemble relevant debugging information (relevant in terms of others can reproduce the error) and:

Contribute

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:

Feature requests

Just use the same workflow as with error reporting.

Notes

  1. ↑ authentication by HTTP (RFC 2617)
  2. ↑ Lightweight Directory Access Protocol (LDAP)
  3. ↑ Central Authentication Service (CAS)
  4. ↑ Pluggable authentication module (PAM)
  5. ↑ Secure Sockets Layer (SSL)
  6. ↑ closure — anonym function without name
  7. ↑ Perl Compatible Regular Expressions (PCRE)
  8. ↑ Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO)
  9. ↑ Single sign-on
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:Auth_remoteuser/en&oldid=6615687"