Extension:Auth remoteuser

MediaWiki extensions manual

Auth_remoteuser Release status: beta
Implementation	User identity
Description	Automatically logs users using the REMOTE_USER environment variable
Author(s)	Rusty Burchfield, User:Otheus Shelling, James Kinsman, Ian Ward Comfort
Latest version	1.1.5 (2012-07-18)
MediaWiki	1.9+
Database changes	No
Composer	mediawiki/auth-remoteuser
License	GPLv2
Download	Download extension Git [?]: Download Git master browse repository (GitHub) commit history repository contributors (GitHub) code review
Parameters $wgAuth $wgAuthRemoteuserAuthz $wgAuthRemoteuserDomain $wgAuthRemoteuserName $wgAuthRemoteuserMail $wgAuthRemoteuserNotify $wgAuthRemoteuserDomain $wgAuthRemoteuserMailDomain
Quarterly downloads	254 (Ranked 25th)
Translate the Auth remoteuser extension if it is available at translatewiki.net

The Auth_remoteuser extension allows integration with the web server's built-in authentication system via the REMOTE_USER environment variable, which is set through HTTP-Auth, LDAP, CAS, PAM, and other authentication systems. The extension automatically logs-in users using the value of the REMOTE_USER environment variable as the MediaWiki username. If an account of that name does not already exist, one is created.

Installation

Configure REMOTE_USER

Apache

Setup your web server's authentication system so that the username is put in the REMOTE_USER environment variable. How this is done will depend on what authentication system you are using. For HTTP authentication, you might setup an .htaccess file as follows (consult the Apache documentation for details):

AuthType Digest
AuthName Wiki
AuthUserFile /etc/passwd-apache
require valid-user

You can also use mod_auth_ldap, mod_auth_cas, mod_auth_pam, or any other authentication system that works with REMOTE_USER. Once you have verified that the REMOTE_USER environment variable is being set to the proper username, continue with installation. You can use phpinfo() to check the contents of REMOTE_USER.

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)

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:

  require_once "$IP/extensions/Auth_remoteuser/Auth_remoteuser.php";
  $wgAuth = new Auth_remoteuser();
  

•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

 Note: Using this extension sets $wgMinimalPasswordLength to zero.

Configuration

$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";
// Don't let anonymous people do things...
$wgGroupPermissions['*']['createaccount']   = false;
$wgGroupPermissions['*']['read']            = false;
$wgGroupPermissions['*']['edit']            = false;

Disabling Login and Logout Links

Since login is now handled by your authentication system, you probably want to disable the pages Special:UserLogin and Special:UserLogout, and remove the login and logout links. Add the following code to LocalSettings.php. The general message "You have requested an invalid special page." is shown if users try to access such unset special pages.

// see http://www.mediawiki.org/wiki/Manual:Hooks/SpecialPage_initList
// and http://www.mediawiki.org/w/Manual:Special_pages
// and http://lists.wikimedia.org/pipermail/mediawiki-l/2009-June/031231.html
// disable login and logout functions for all users
function LessSpecialPages(&$list) {
	unset( $list['Userlogout'] );
	unset( $list['Userlogin'] );
	return true;
}
$wgHooks['SpecialPage_initList'][]='LessSpecialPages';

// http://www.mediawiki.org/wiki/Extension:Windows_NTLM_LDAP_Auto_Auth
// remove login and logout buttons for all users
function StripLogin(&$personal_urls, &$wgTitle) {  
	unset( $personal_urls["login"] );
	unset( $personal_urls["logout"] );
	unset( $personal_urls['anonlogin'] );
	return true;
}
$wgHooks['PersonalUrls'][] = 'StripLogin';

How It Works

When the user first hits the wiki, the web server authenticates the user and sets the REMOTE_USER variable. The MediaWiki code is then invoked. At the end of Setup.php, before any real processing begins, the extension's hook is called. This code depends primarily on the fact that user is always authenticated by the web server prior to any MediaWiki code being executed.

If the user already has an existing, valid MediaWiki session and account, the hook takes no further action. MediaWiki already has what it needs.

If the user has an existing valid MediaWiki account, but not a session, the hook simply ensures that MediaWiki uses the username in REMOTE_USER in creating a session, cookies, etc, and takes no further action.

If the user has not created an account, the hook uses MediaWiki's initUser() function to create an account, and sets various default user-options. See the hook's initUser function to change these default options. The hook then issues a Location directive to the browser, using the same URL that was called. When the browser reloads, the user account has been created, a session is now created, and MediaWiki behaves as normal.

Troubleshooting

Cookies

If the user has cookies turned off, they will probably find themselves in an endless redirection loop.

Password

Contrary to previous versions of Mediawiki, the authenticateUserData() function will automatically fail if an empty password is provided, e.g., within a faux login call; for MediaWiki v1.17.0, try using just a space instead.

Backups

If your backups don't work, try setting the REMOTE_USER environment variable manually:

REMOTE_USER="wikiusername" php dumpBackup.php  --full

Secure Server Settings

Make sure your server sets HTTPS_KEYSIZE only when in SSL/https mode. If not, change the hooking function accordingly.

Implementation Details

Parts of this section may be out-of-date.

Initialization

This extension makes use of the "Hook" at the end of Setup.php. This allows the extension to perform initialisation in the fully initialized environment.

The extension's initialization code adds the name of the extension's primary workhorse function to $wgExtensionFunctions. If the array doesn't exist or is not an array, it is assumed that it is a single string and then converted into an array. All this is done only if REMOTE_USER is actually set. If it's not set, there is no point to the extension.

AuthPlugin routines

Several routines from AuthPlugin must be overridden for correct operation to occur.

• userExists() must return true always. The method is misleading. It's only called by MediaWiki in determining whether the user exists in the security context, not whether the user is in the MediaWiki database.
• authenticate() is a tricky one. My code returns true whenever REMOTE_USER is set, false otherwise. One might want anonymous users to see the site, but not be authenticated to make changes. This is why this depends on the REMOTE_USER setting.
• autoCreate() should always be true. This gets checked only within initUser(), ie, when the Web Server has authenticated a user unknown to the Wiki.
• strict() is set to true based on the word of the author of the previous version of this extension.
• modifyUITemplate configures the user interface so that the user does not see configuration options which don't apply to him. I'm not certain this works correctly.

initUser()

initUser() -- configure this routine according to your particular environment to update the email address and other information in the MediaWiki database to match the authentication source.

The hooking function

1. If the page requested is either Special:Userlogout or Special:Userlogin, do nothing.
2. Try to load the User session. If successful, and the User is logged in, do nothing.
3. Call User::newFromName ( REMOTE_USER ). If the username is invalid, just do nothing.
4. Set $wgUser to the user info returned from newFromName.
5. If the getID is non-zero, the user is already known to MediaWiki:
   1. set _REQUEST['wpName'] to the REMOTE_USER (This seems to be necessary from LoginForm())
   2. return
6. Create a New Wiki User
   1. Create a new LoginForm(). A form isn't actually displayed, but the constructor includes code that sets up a quasi-global user variable.
   2. Call initUser()
      • wgUser->initUser() will invoke wgAuth->initUser().
      • That's where the user defaults are set. You can also set them here after the call to initUser()
   3. Call wgUser->saveSettings(). This is required to save the settings from above to the database and appears to be a bug in LoginForm::initUser().
   4. Re-create the calling URL and redirect the browser to it. Note: the HTTPS portion has not been tested and may be server-specific!