LoginNameAliasesPlugin < Extensions

You are here: Foswiki>Extensions Web>SupportQuestions>Question172>LoginNameAliasesPlugin (revision 2) (raw view)

<!--
This topic is part of the documentation for LoginNameAliasesPlugin and is
automatically generated from Subversion. You can edit it, but if you do,
please make sure the maintainer of the extension knows about your changes,
otherwise your edits might be lost the next time the topic is uploaded.

If you want to report an error in the topic, please raise a report at
http://foswiki.org/Tasks/LoginNameAliasesPlugin
-->

---+ <nop>LoginNameAliasesPlugin

This plugin is used to map login names (typically determined by the REMOTE_USER
variable set by the web server) to usernames.  

---+ !LoginNameAliasesPlugin documentation
In an intranet (<nop>PubCookie, windows Domains etc) users are identified to Foswiki via 
a REMOTE_USER variable that is set by the webserver.  This can lead to the following issues:

	* This remote user value may not be suitable for direct use as a Foswiki login name 
		* e.g. it may contain special characters, or be a windows Domain such as WORKGROUP/UserName
	* The same person may connect to Foswiki via various authentication domains or methods. For example, !JohnSmith may connect both as jsmith@DOMAIN1 and johns@DOMAIN2, and should be identified as the same user to Foswiki.
	* Non-registered but identified users may connect to Foswiki in this way 
	and one may wish to map such users to a particular registered user.

These issues have been discussed in several Foswiki support topics
on http://foswiki.org. Proposed solutions have often involved making small changes to Foswiki source files. The !LoginNameAliasesPlugin makes use of initializeUserHandler and attempts to provide a configurable, plugin-based solution to some of these problems. It was originally
designed to be used in a intranet environment where all registered users have both a !WikiName and a user name (which is often the same as a Unix or Windows username).

---++ Settings
Behavior of this plugin is controlled through the following settings in =configure= (in the Extensions / LoginNameAliasesPlugin section). 

	* MAP_BLANK_USER = &lt;login name&gt; (replaces the internal guest user)
	* USE_ALIASES = &lt;boolean&gt;
	* REMOVE_PREFIX = &lt;string&gt;
	* REMOVE_SUFFIX = &lt;string&gt;
    * CHANGE_CASE = =none,upper,lower,uppercasefirst=
	* MAP_UNREGISTERED = &lt;login name&gt;
	* RETURN_NOTHING_IF_UNCHANGED = &lt;boolean&gt;
	* LOGGING = &lt;boolean&gt;
	* DEBUG = &lt;boolean&gt;
 

In addition to these settings, the plugin topic may contain aliases. An alias entry is a single line of the form:
<pre>
&lt;multiple of 3 spaces&gt;*&lt;space&gt;ALIAS:&lt;space&gt;&lt;string&gt;&lt;space&gt;&lt;username&gt;
</pre>
For example:
<pre>
	* ALIAS: johns@BAR.COM jsmith
</pre>
If the user (as passed to the plugin) is an exact match for the first string, the plugin will return the given username. 

---++ How it works
When it runs, the plugin performs the following steps in  succession to the username passed to initializeUserHandler.  

	1. If the username is blank return either "", or the value of MAP_BLANK_USER if it is set. *Note:* a username that would evaluate to false in Perl (e.g. the user "0") is treated as blank.
	2. If USE_ALIASES is set, the alias list is checked for a match and the first match found is  returned. 
	3. If REMOVE_PREFIX is set, an attempt is made to remove that string from the beginning of the username (quotemeta is applied to the string before it is used).
	4. If REMOVE_SUFFIX is set, an attempt is made to remove that string from the end of the username (quotemeta is applied to the string before it is used).
	4. If CHANGE_CASE is set to =upper=, convert all letters to uppercase, =lower= to lowercase, and =uppercasefirst= convert _only_ the first letter to upper-case.
	5. The MAP_BLANK_USER check from step 1 is applied again, since steps 3 or 4 may have zapped the whole username.
	6. If MAP_UNREGISTERED is set, then check to see if the user has a !WikiName.  If not, then  return the value of MAP_UNREGISTERED. If the user already has a !WikiName, go to step 7. *Note:* This setting will not work unless doMapUserToWikiName is set to 1 in Foswiki.cfg.
	7. If the username after the PREFIX/SUFFIX transformations is different from 
	the  one passed to us in the original username argument, the new name will
	be returned. If it is the same as the original one, then the original username will be returned, unless RETURN_NOTHING_IF_UNCHANGED is true.

If LOGGING is turned on, the following fields will be logged to to the file (workdir)/_logfile.txt: timestamp, $ENV{'REMOTE_ADDR'}, $ENV{'REMOTE_USER'}, the username that was passed to the plugin, the username that the plugin returned.
This is useful for debugging and keeping a record of user names before they are mapped. Note that the logfile must be writable by the web server (just like other Foswiki log files).

---++ Security
There are obvious security risks with allowing arbitrary user names to get mapped to arbitrary Foswiki users. To mitigate these risks:
	* The plugin configuration topic, [[%SYSTEMWEB%.LoginNameAliasesPlugin][%SYSTEMWEB%.LoginNameAliasesPlugin]], should have
	access permissions set such that only people in the %MAINWEB%.AdminGroup	(or other people who can be trusted) can change it.  By default, the topic is distributed with this access restriction.

---++ Caution
Misconfiguration of this plugin could cause problems for Foswiki operation, and/or create various security problems.


---++ Aliases

If you enable ={LoginNameAliasesPlugin}{USE_ALIASES}= in configure, the following Alias definitions are used.

<verbatim>

Sample alias (disabled by a # character):
	* #ALIAS: foo@BAR.COM foobar 

</verbatim>

The currently logged in user's =%!USERINFO%= is
   * %USERINFO%


	* Set ALLOWTOPICCHANGE = %MAINWEB%.AdminGroup

---++ Installation
You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.


 
---++ Plugin Info

|  Plugin Author: | Foswiki:Main.SvenDowideit & TWiki:Main/ClaussStrauch |
|  Plugin Version: | 13982 (2012-02-15) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  15 Feb 2012: | add CHANGE_CASE option - to help normalise the login-names from different browsers |
|  8 Jul 2009: | ported to Foswiki by Foswiki:Main.SvenDowideit, and changed to begin to use current practices |
|  23 Jul 2004: | Initial version |
|  Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |

PackageForm edit

ExtensionClassification	Admin, Security
ExtensionType	PluginPackage
Compatibility	1.0
DemoUrl	http://
SupportUrl	LoginNameAliasesPlugin
DevelopedInSVN	Yes
ModificationPolicy	PleaseFeelFreeToModify

Topic attachments
I	Attachment	Action	Size	Date	Who
md5	LoginNameAliasesPlugin.md5	manage	0.2 K	15 Feb 2012 - 03:44	SvenDowideit
sha1	LoginNameAliasesPlugin.sha1	manage	0.2 K	15 Feb 2012 - 03:45	SvenDowideit
tgz	LoginNameAliasesPlugin.tgz	manage	7.3 K	15 Feb 2012 - 03:44	SvenDowideit
zip	LoginNameAliasesPlugin.zip	manage	9.6 K	15 Feb 2012 - 03:44	SvenDowideit
EXT	LoginNameAliasesPlugin_installer	manage	4.2 K	15 Feb 2012 - 03:44	SvenDowideit

Topic revision: r2 - 15 Feb 2012, SvenDowideit

Extensions

Quick Links

Tools

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. see CopyrightStatement.