TWiki/TWikiUserMappingDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::_UserMapping="></a> Package =TWiki::UserMapping
   2
   3 This is a virtual base class (a.k.a an interface) for all user mappers. It is **not** useable as a mapping in TWiki - use the [[BaseUserMapping]] for default behaviour.
   4
   5 User mapping is the process by which TWiki maps from a username (a login name) to a display name and back. It is also where groups are maintained.
   6
   7 See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for the default implementations of this interface.
   8
   9 If you want to write a user mapper, you will need to implement the methods described in this class.
  10
  11 User mappings work by mapping both login names and display names to a _canonical user id_. This user id is composed from a prefix that defines the mapper in use (something like 'BaseUserMapping\_' or 'LdapUserMapping\_') and a unique user id that the mapper uses to identify the user.
  12
  13 The null prefix is reserver for the [[TWikiUserMapping]] for compatibility with old TWiki releases.
  14
  15 **_Note:_** in all the following documentation, `$cUID` refers to a **canonical user id**.
  16
  17 <div>
  18   <ul>
  19     <li><a href="#Package =TWiki::_UserMapping="> Package TWiki::UserMapping</a><ul>
  20         <li><a href="#PROTECTED _ClassMethod new ($ses"> PROTECTED ClassMethod new ($session, $mapping_id)</a></li>
  21         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  22         <li><a href="#ObjectMethod *login_TemplateName"> ObjectMethod loginTemplateName <tt>() -&gt; $templateFile</tt></a></li>
  23         <li><a href="#ObjectMethod *supportsRegistrati"> ObjectMethod supportsRegistration <tt>() -&gt; $boolean</tt></a></li>
  24         <li><a href="#ObjectMethod <strong>handlesUser</strong> ($cUI"> ObjectMethod handlesUser <tt>($cUID,$login,$wikiname) -&gt; $boolean</tt></a></li>
  25         <li><a href="#ObjectMethod <strong>login2cUID</strong> ($logi"> ObjectMethod login2cUID <tt>($login,$dontcheck) -&gt; cUID</tt></a></li>
  26         <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -&gt; login</tt></a></li>
  27         <li><a href="#ObjectMethod <strong>addUser</strong> ($login,$"> ObjectMethod addUser <tt>($login,$wikiname,$password,$emails) -&gt; $cUID</tt></a></li>
  28         <li><a href="#ObjectMethod <strong>removeUser</strong> ($cUID"> ObjectMethod removeUser <tt>($cUID) -&gt; $boolean</tt></a></li>
  29         <li><a href="#ObjectMethod <strong>get_WikiName</strong> ($cU"> ObjectMethod getWikiName <tt>($cUID) -&gt; $wikiname</tt></a></li>
  30         <li><a href="#ObjectMethod <strong>userExists</strong> ($cUID"> ObjectMethod userExists <tt>($cUID) -&gt; $boolean</tt></a></li>
  31         <li><a href="#ObjectMethod <strong>eachUser</strong> () -> TW"> ObjectMethod eachUser <tt>() -&gt; TWiki::ListIteratorofcUIDs</tt></a></li>
  32         <li><a href="#ObjectMethod *each_GroupMember*"> ObjectMethod eachGroupMember <tt>($group) -&gt; TWiki::ListIteratorofcUIDs</tt></a></li>
  33         <li><a href="#ObjectMethod <strong>isGroup</strong> ($name) -"> ObjectMethod isGroup <tt>($name) -&gt; boolean</tt></a></li>
  34         <li><a href="#ObjectMethod <strong>eachGroup</strong> () -> T"> ObjectMethod eachGroup <tt>() -&gt; TWiki::ListIteratorofgroupnames</tt></a></li>
  35         <li><a href="#ObjectMethod <strong>eachMembership</strong> ($"> ObjectMethod eachMembership <tt>($cUID) -&gt; TWiki::ListIteratorofgroupsthisuserisin</tt></a></li>
  36         <li><a href="#ObjectMethod <strong>isAdmin</strong> ($cUID) -"> ObjectMethod isAdmin <tt>($cUID) -&gt; $boolean</tt></a></li>
  37         <li><a href="#ObjectMethod <strong>is_InGroup</strong> ($cUID"> ObjectMethod isInGroup <tt>($cUID,$group) -&gt; $bool</tt></a></li>
  38         <li><a href="#ObjectMethod *find_UserByEmail*"> ObjectMethod findUserByEmail <tt>($email) -&gt; \@users</tt></a></li>
  39         <li><a href="#ObjectMethod <strong>getEmails</strong> ($name)"> ObjectMethod getEmails <tt>($name) -&gt; @emailAddress</tt></a></li>
  40         <li><a href="#ObjectMethod <strong>setEmails</strong> ($cUID,"> ObjectMethod setEmails <tt>($cUID,@emails)</tt></a></li>
  41         <li><a href="#ObjectMethod *find_UserByWikiNam"> ObjectMethod findUserByWikiName <tt>($wikiname) -&gt; listofcUIDsassociatedwiththatwikiname</tt></a></li>
  42         <li><a href="#ObjectMethod <strong>checkPassword</strong> ($l"> ObjectMethod checkPassword <tt>($login,$passwordU) -&gt; $boolean</tt></a></li>
  43         <li><a href="#ObjectMethod <strong>setPassword</strong> ($cUI"> ObjectMethod setPassword <tt>($cUID,$newPassU,$oldPassU) -&gt; $boolean</tt></a></li>
  44         <li><a href="#ObjectMethod <strong>passwordError</strong> ()"> ObjectMethod passwordError <tt>() -&gt; $string</tt></a></li>
  45       </ul>
  46     </li>
  47   </ul>
  48 </div>
  49
  50 ## <a name="PROTECTED _ClassMethod new ($ses"></a> PROTECTED [[ClassMethod]] new ($session, $mapping\_id)
  51
  52 Construct a user mapping object, using the given mapping id.
  53
  54 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
  55
  56 Break circular references.
  57
  58 ## <a name="ObjectMethod &lt;strong&gt;login_TemplateName"></a> [[ObjectMethod]] \*loginTemplateName `() -> $templateFile`
  59
  60 Allows [[UserMappings]] to come with customised login screens - that should preferably only over-ride the UI function
  61
  62 Default is "login"
  63
  64 ## <a name="ObjectMethod &lt;strong&gt;supportsRegistrati"></a> [[ObjectMethod]] \*supportsRegistration `() -> $boolean`
  65
  66 Return true if the [[UserMapper]] supports registration (ie can create new users)
  67
  68 Default is **false**
  69
  70 ## <a name="ObjectMethod &lt;strong&gt;handlesUser&lt;/strong&gt; ($cUI"></a> [[ObjectMethod]] **handlesUser** `($cUID,$login,$wikiname) -> $boolean`
  71
  72 Called by the TWiki::Users object to determine which loaded mapping to use for a given user (must be fast).
  73
  74 The user can be identified by any of $cUID, $login or $wikiname. Any of these parameters may be undef, and they should be tested in order; cUID first, then login, then wikiname.
  75
  76 ## <a name="ObjectMethod &lt;strong&gt;login2cUID&lt;/strong&gt; ($logi"></a> [[ObjectMethod]] **login2cUID** `($login,$dontcheck) -> cUID`
  77
  78 Convert a login name to the corresponding canonical user name. The canonical name can be any string of 7-bit alphanumeric and underscore characters, and must map 1:1 to the login name. (undef on failure)
  79
  80 (if $dontcheck is true, return a cUID for a nonexistant user too. This is used for registration)
  81
  82 Subclasses **must** implement this method.
  83
  84 Note: This method was previously (in TWiki 4.2.0) known as getCanonicalUserID. The name was changed to avoid confusion with TWiki::Users::getCanonicalUserID, which has a more generic function. However to support older user mappers, getCanonicalUserID will still be called if login2cUID is not defined.
  85
  86 ## <a name="ObjectMethod &lt;strong&gt;get_LoginName&lt;/strong&gt; ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> login`
  87
  88 Converts an internal cUID to that user's login (undef on failure)
  89
  90 Subclasses **must** implement this method.
  91
  92 ## <a name="ObjectMethod &lt;strong&gt;addUser&lt;/strong&gt; ($login,$"></a> [[ObjectMethod]] **addUser** `($login,$wikiname,$password,$emails) -> $cUID`
  93
  94 Add a user to the persistant mapping that maps from usernames to wikinames and vice-versa.
  95
  96 $login and $wikiname must be acceptable to $TWiki::cfg\{NameFilter\}. $login must **always** be specified. $wikiname may be undef, in which case the user mapper should make one up.
  97
  98 This function must return a canonical user id that it uses to uniquely identify the user. This can be the login name, or the wikiname if they are all guaranteed unigue, or some other string consisting only of 7-bit alphanumerics and underscores.
  99
 100 If you fail to create a new user (for eg your Mapper has read only access),
 101
 102         throw Error::Simple('Failed to add user: '.$error);
 103
 104 where $error is a descriptive string.
 105
 106 Throws an Error::Simple if user adding is not supported (the default).
 107
 108 ## <a name="ObjectMethod &lt;strong&gt;removeUser&lt;/strong&gt; ($cUID"></a> [[ObjectMethod]] **removeUser** `($cUID) -> $boolean`
 109
 110 Delete the users entry from this mapper. Throws an Error::Simple if user removal is not supported (the default).
 111
 112 ## <a name="ObjectMethod &lt;strong&gt;get_WikiName&lt;/strong&gt; ($cU"></a> [[ObjectMethod]] **getWikiName** `($cUID) -> $wikiname`
 113
 114 Map a canonical user name to a wikiname.
 115
 116 Returns the $cUID by default.
 117
 118 ## <a name="ObjectMethod &lt;strong&gt;userExists&lt;/strong&gt; ($cUID"></a> [[ObjectMethod]] **userExists** `($cUID) -> $boolean`
 119
 120 Determine if the user already exists or not. Whether a user exists or not is determined by the password manager.
 121
 122 Subclasses **must** implement this method.
 123
 124 ## <a name="ObjectMethod &lt;strong&gt;eachUser&lt;/strong&gt; () - TWi"></a> [[ObjectMethod]] **eachUser** `() -> TWiki::ListIteratorofcUIDs`
 125
 126 Get an iterator over the list of all the registered users **not** including groups.
 127
 128 Subclasses **must** implement this method.
 129
 130 ## <a name="ObjectMethod &lt;strong&gt;each_GroupMember*"></a><a name="ObjectMethod *each_GroupMember&lt;/strong&gt; "></a> [[ObjectMethod]] **eachGroupMember** `($group) -> TWiki::ListIteratorofcUIDs`
 131
 132 Return a iterator over the canonical user ids of users that are members of this group. Should only be called on groups.
 133
 134 Note that groups may be defined recursively, so a group may contain other groups. This method should **only** return users i.e. all contained groups should be fully expanded.
 135
 136 Subclasses **must** implement this method.
 137
 138 ## <a name="ObjectMethod &lt;strong&gt;isGroup&lt;/strong&gt; ($name) -"></a> [[ObjectMethod]] **isGroup** `($name) -> boolean`
 139
 140 Establish if a user refers to a group or not. If $name is not a group name it will probably be a canonical user id, though that should not be assumed.
 141
 142 Subclasses **must** implement this method.
 143
 144 ## <a name="ObjectMethod &lt;strong&gt;eachGroup&lt;/strong&gt; () - TW"></a> [[ObjectMethod]] **eachGroup** `() -> TWiki::ListIteratorofgroupnames`
 145
 146 Get an iterator over the list of all the groups.
 147
 148 Subclasses **must** implement this method.
 149
 150 ## <a name="ObjectMethod &lt;strong&gt;eachMembership&lt;/strong&gt; ($"></a> [[ObjectMethod]] **eachMembership** `($cUID) -> TWiki::ListIteratorofgroupsthisuserisin`
 151
 152 Return an iterator over the names of groups that $cUID is a member of.
 153
 154 Subclasses **must** implement this method.
 155
 156 ## <a name="ObjectMethod &lt;strong&gt;isAdmin&lt;/strong&gt; ($cUID) -"></a> [[ObjectMethod]] **isAdmin** `($cUID) -> $boolean`
 157
 158 True if the user is an administrator.
 159
 160 ## <a name="ObjectMethod &lt;strong&gt;is_InGroup&lt;/strong&gt; ($cUID"></a> [[ObjectMethod]] **isInGroup** `($cUID,$group) -> $bool`
 161
 162 Test if the user identified by $cUID is in the given group. The default implementation iterates over all the members of $group, which is rather inefficient.
 163
 164 ## <a name="ObjectMethod &lt;strong&gt;find_UserByEmail*"></a><a name="ObjectMethod *find_UserByEmail&lt;/strong&gt; "></a> [[ObjectMethod]] **findUserByEmail** `($email) -> \@users`
 165
 166 - `$email` - email address to look up
 167
 168 Return a list of canonical user names for the users that have this email registered with the password manager or the user mapping manager.
 169
 170 ## <a name="ObjectMethod &lt;strong&gt;getEmails&lt;/strong&gt; ($name)"></a> [[ObjectMethod]] **getEmails** `($name) -> @emailAddress`
 171
 172 If $name is a cUID, return that user's email addresses. If it is a group, return the addresses of everyone in the group.
 173
 174 Duplicates should be removed from the list.
 175
 176 ## <a name="ObjectMethod &lt;strong&gt;setEmails&lt;/strong&gt; ($cUID,"></a> [[ObjectMethod]] **setEmails** `($cUID,@emails)`
 177
 178 Set the email address(es) for the given user.
 179
 180 ## <a name="ObjectMethod &lt;strong&gt;find_UserByWikiNam"></a> [[ObjectMethod]] \*findUserByWikiName `($wikiname) -> listofcUIDsassociatedwiththatwikiname`
 181
 182 - `$wikiname` - wikiname to look up
 183
 184 Return a list of canonical user names for the users that have this wikiname. Since a single wikiname might be used by multiple login ids, we need a list.
 185
 186 Note that if $wikiname is the name of a group, the group will **not** be expanded.
 187
 188 Subclasses **must** implement this method.
 189
 190 ## <a name="ObjectMethod &lt;strong&gt;checkPassword&lt;/strong&gt; ($l"></a> [[ObjectMethod]] **checkPassword** `($login,$passwordU) -> $boolean`
 191
 192 Finds if the password is valid for the given login. This is called using a login name rather than a cUID because the user may not have been mapped at the time it is called.
 193
 194 Returns 1 on success, undef on failure.
 195
 196 Default behaviour is to return 1.
 197
 198 ## <a name="ObjectMethod &lt;strong&gt;setPassword&lt;/strong&gt; ($cUI"></a> [[ObjectMethod]] **setPassword** `($cUID,$newPassU,$oldPassU) -> $boolean`
 199
 200 If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
 201
 202 If $oldPassU is not correct and not 1, will return 0.
 203
 204 If $oldPassU is 1, will force the change irrespective of the existing password, adding the user if necessary.
 205
 206 Otherwise returns 1 on success, undef on failure.
 207
 208 Default behaviour is to fail.
 209
 210 ## <a name="ObjectMethod &lt;strong&gt;passwordError&lt;/strong&gt; ()"></a><a name="ObjectMethod &lt;strong&gt;passwordError&lt;/strong&gt; () "></a> [[ObjectMethod]] **passwordError** `() -> $string`
 211
 212 Returns a string indicating the error that happened in the password handlers TODO: these delayed errors should be replaced with Exceptions.
 213
 214 returns undef if no error (the default)