1 # <a name="Package <code>TWiki::Users="></a> Package =TWiki::Users
3 This package provides services for the lookup and manipulation of login and wiki names of users, and their authentication.
5 It is a Facade that presents a common interface to the User Mapping and Password modules. The rest of the core should **only** use the methods of this package, and should **never** call the mapping or password managers directly.
7 TWiki uses the concept of a _login name_ which is used to authenticate a user. A login name maps to a _wiki name_ that is used to identify the user for display. Each login name is unique to a single user, though several login names may map to the same wiki name.
9 Using this module (and the associated plug-in user mapper) TWiki supports the concept of _groups_. Groups are sets of login names that are treated equally for the purposes of access control. Group names do not have to be wiki names, though it is helpful for display if they are.
11 Internally in the code TWiki uses something referred to as a \_canonical user id\_ or just _user id_. The user id is also used externally to uniquely identify the user when (for example) recording topic histories. The user id is **usually** just the login name, but it doesn't need to be. It just has to be a unique 7-bit alphanumeric and underscore string that can be mapped to/from login and wiki names by the user mapper.
13 The canonical user id should **never** be seen by a user. On the other hand, core code should never use anything **but** a canonical user id to refer to a user.
17 - A **login name** is the name used to log in to TWiki. Each login name is assumed to be unique to a human. The Password module is responsible for authenticating and manipulating login names.
18 - A **canonical user id** is an internal TWiki representation of a user. Each canonical user id maps 1:1 to a login name.
19 - A **wikiname** is how a user is displayed. Many user ids may map to a single wikiname. The user mapping module is responsible for mapping the user id to a wikiname.
20 - A **group id** represents a group of users and other groups. The user mapping module is responsible for mapping from a group id to a list of canonical user ids for the users in that group.
21 - An **email** is an email address asscoiated with a **login name**. A single login name may have many emails.
25 - wherever the code references $cUID, its a canonical\_id
26 - wherever the code references $group, its a group\_name
27 - $name may be a group or a cUID
31 <li><a href="#Package =TWiki::Users="> Package TWiki::Users</a><ul>
32 <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
33 <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
34 <li><a href="#ObjectMethod *login_TemplateName"> ObjectMethod loginTemplateName <tt>() -> templateFile</tt></a></li>
35 <li><a href="#ObjectMethod *supportsRegistrati"> ObjectMethod supportsRegistration <tt>() -> boolean</tt></a></li>
36 <li><a href="#ObjectMethod <strong>initialiseUser</strong> ($"> ObjectMethod initialiseUser <tt>($login) -> $cUID</tt></a></li>
37 <li><a href="#randomPassword()"> randomPassword()</a></li>
38 <li><a href="#ObjectMethod <strong>addUser</strong> ($login,$"> ObjectMethod addUser <tt>($login,$wikiname,$password,$emails) -> $cUID</tt></a></li>
39 <li><a href="#StaticMethod <strong>map_Login2cUID</strong> ($"> StaticMethod mapLogin2cUID <tt>($login) -> $cUID</tt></a></li>
40 <li><a href="#ObjectMethod *get_CanonicalUserI"> ObjectMethod getCanonicalUserID <tt>($identifier) -> $cUID</tt></a></li>
41 <li><a href="#ObjectMethod *find_UserByWikiNam"> ObjectMethod findUserByWikiName <tt>($wn) -> \@users</tt></a></li>
42 <li><a href="#ObjectMethod *find_UserByEmail*"> ObjectMethod findUserByEmail <tt>($email) -> \@users</tt></a></li>
43 <li><a href="#ObjectMethod <strong>getEmails</strong> ($name)"> ObjectMethod getEmails <tt>($name) -> @emailAddress</tt></a></li>
44 <li><a href="#ObjectMethod <strong>setEmails</strong> ($cUID,"> ObjectMethod setEmails <tt>($cUID,@emails)</tt></a></li>
45 <li><a href="#ObjectMethod <strong>isAdmin</strong> ($cUID) -"> ObjectMethod isAdmin <tt>($cUID) -> $boolean</tt></a></li>
46 <li><a href="#ObjectMethod <strong>is_InList</strong> ($cUID,"> ObjectMethod isInList <tt>($cUID,$list) -> $boolean</tt></a></li>
47 <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -> $login</tt></a></li>
48 <li><a href="#ObjectMethod <strong>get_WikiName</strong> ($cU"> ObjectMethod getWikiName <tt>($cUID) -> $wikiName</tt></a></li>
49 <li><a href="#ObjectMethod <strong>web_DotWikiName</strong> ("> ObjectMethod webDotWikiName <tt>($cUID) -> $webDotWiki</tt></a></li>
50 <li><a href="#ObjectMethod <strong>userExists</strong> ($cUID"> ObjectMethod userExists <tt>($cUID) -> $boolean</tt></a></li>
51 <li><a href="#ObjectMethod <strong>eachUser</strong> () -> TW"> ObjectMethod eachUser <tt>() -> TWiki::IteratorofcUIDs</tt></a></li>
52 <li><a href="#ObjectMethod <strong>eachGroup</strong> () -> T"> ObjectMethod eachGroup <tt>() -> TWiki::ListIteratorofgroupnames</tt></a></li>
53 <li><a href="#ObjectMethod *each_GroupMember*"> ObjectMethod eachGroupMember <tt>($group) -> $iterator</tt></a></li>
54 <li><a href="#ObjectMethod <strong>isGroup</strong> ($name) -"> ObjectMethod isGroup <tt>($name) -> boolean</tt></a></li>
55 <li><a href="#ObjectMethod <strong>is_InGroup</strong> ($cUID"> ObjectMethod isInGroup <tt>($cUID,$group) -> $boolean</tt></a></li>
56 <li><a href="#ObjectMethod <strong>eachMembership</strong> ($"> ObjectMethod eachMembership <tt>($cUID) -> $iterator</tt></a></li>
57 <li><a href="#ObjectMethod <strong>checkLogin</strong> ($logi"> ObjectMethod checkLogin <tt>($login,$passwordU) -> $boolean</tt></a></li>
58 <li><a href="#ObjectMethod <strong>setPassword</strong> ($cUI"> ObjectMethod setPassword <tt>($cUID,$newPassU,$oldPassU) -> $boolean</tt></a></li>
59 <li><a href="#ObjectMethod <strong>passwordError</strong> ()"> ObjectMethod passwordError <tt>() -> $string</tt></a></li>
60 <li><a href="#ObjectMethod <strong>removeUser</strong> ($cUID"> ObjectMethod removeUser <tt>($cUID) -> $boolean</tt></a></li>
66 ## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
68 Construct the user management object that is the facade to the [[BaseUserMapping]] and the user mapping chosen in the configuration.
70 ## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
72 Break circular references.
74 ## <a name="ObjectMethod <strong>login_TemplateName"></a> [[ObjectMethod]] \*loginTemplateName `() -> templateFile`
76 allows [[UserMappings]] to come with customised login screens - that should preffereably only over-ride the UI function
78 ## <a name="ObjectMethod <strong>supportsRegistrati"></a> [[ObjectMethod]] \*supportsRegistration `() -> boolean`
80 #return 1 if the main [[UserMapper]] supports registration (ie can create new users)
82 ## <a name="ObjectMethod <strong>initialiseUser</strong> ($"></a> [[ObjectMethod]] **initialiseUser** `($login) -> $cUID`
84 Given a login (which must have been authenticated) determine the cUID that corresponds to that user. This method is used from TWiki.pm to map the $REMOTE\_USER to a cUID.
86 ## <a name="randomPassword()"></a> randomPassword()
88 Static function that returns a random password. This function is not used in this module; it is provided as a service for other modules, such as custom mappers and registration modules.
90 ## <a name="ObjectMethod <strong>addUser</strong> ($login,$"></a> [[ObjectMethod]] **addUser** `($login,$wikiname,$password,$emails) -> $cUID`
92 - `$login` - user login name. If `undef`, `$wikiname` will be used as the login name.
93 - `$wikiname` - user wikiname. If `undef`, the user mapper will be asked to provide it.
94 - `$password` - password. If undef, a password will be generated.
96 Add a new TWiki user identity, returning the canonical user id for the new user. Used ONLY for user registration.
98 The user is added to the password system (if there is one, and if it accepts changes). If the user already exists in the password system, then the password is checked and an exception thrown if it doesn't match. If there is no existing user, and no password is given, a random password is generated.
100 $login can be undef; $wikiname must always have a value.
102 The return value is the canonical user id that is used by TWiki to identify the user.
104 ## <a name="StaticMethod <strong>map_Login2cUID</strong> ($"></a> [[StaticMethod]] **mapLogin2cUID** `($login) -> $cUID`
106 This function maps an arbitrary string into a valid cUID. The transformation is reversible, but the function is not idempotent (a cUID passed to this function will NOT be returned unchanged). The generated cUID will be unique for the given login name.
108 This static function is designed to be called from custom user mappers that support 1:1 login-to-cUID mappings.
110 ## <a name="ObjectMethod <strong>get_CanonicalUserI"></a> [[ObjectMethod]] \*getCanonicalUserID `($identifier) -> $cUID`
112 Works out the TWiki canonical user identifier for the user who either (1) logs in with the login name $identifier or (2) has the wikiname $identifier.
114 The canonical user ID is an alphanumeric string that is unique to the login name, and can be mapped back to a login name and the corresponding wiki name using the methods of this class.
116 Note that if the login name to wiki name mapping is not 1:1, this method will map a wikiname to one of the login names that corresponds to the wiki name, but there is no guarantee which one.
118 Returns undef if the user does not exist.
120 ## <a name="ObjectMethod <strong>find_UserByWikiNam"></a> [[ObjectMethod]] \*findUserByWikiName `($wn) -> \@users`
122 - `$wn` - wikiname to look up
124 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.
126 If $wn is the name of a group, the group will **not** be expanded.
128 ## <a name="ObjectMethod <strong>find_UserByEmail*"></a><a name="ObjectMethod *find_UserByEmail</strong> "></a> [[ObjectMethod]] **findUserByEmail** `($email) -> \@users`
130 - `$email` - email address to look up
132 Return a list of canonical user names for the users that have this email registered with the user mapping managers.
134 ## <a name="ObjectMethod <strong>getEmails</strong> ($name)"></a> [[ObjectMethod]] **getEmails** `($name) -> @emailAddress`
136 If $name is a cUID, return their email addresses. If it is a group, return the addresses of everyone in the group.
138 The password manager and user mapping manager are both consulted for emails for each user (where they are actually found is implementation defined).
140 Duplicates are removed from the list.
142 ## <a name="ObjectMethod <strong>setEmails</strong> ($cUID,"></a> [[ObjectMethod]] **setEmails** `($cUID,@emails)`
144 Set the email address(es) for the given user. The password manager is tried first, and if it doesn't want to know the user mapping manager is tried.
146 ## <a name="ObjectMethod <strong>isAdmin</strong> ($cUID) -"></a> [[ObjectMethod]] **isAdmin** `($cUID) -> $boolean`
148 True if the user is an admin
150 - is $TWiki::cfg\{SuperAdminGroup\}
151 - is a member of the $TWiki::cfg\{SuperAdminGroup\}
153 ## <a name="ObjectMethod <strong>is_InList</strong> ($cUID,"></a> [[ObjectMethod]] **isInList** `($cUID,$list) -> $boolean`
155 Return true if $cUID is in a list of user **wikinames**, **logins** and group ids.
157 The list may contain the conventional web specifiers (which are ignored).
159 ## <a name="ObjectMethod <strong>get_LoginName</strong> ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> $login`
161 Get the login name of a user. Returns undef if the user is not known.
163 ## <a name="ObjectMethod <strong>get_WikiName</strong> ($cU"></a> [[ObjectMethod]] **getWikiName** `($cUID) -> $wikiName`
165 Get the wikiname to display for a canonical user identifier.
167 Can return undef if the user is not in the mapping system (or the special case from initialiseUser)
169 ## <a name="ObjectMethod <strong>web_DotWikiName</strong> ("></a> [[ObjectMethod]] **webDotWikiName** `($cUID) -> $webDotWiki`
171 Return the fully qualified wikiname of the user
173 ## <a name="ObjectMethod <strong>userExists</strong> ($cUID"></a> [[ObjectMethod]] **userExists** `($cUID) -> $boolean`
175 Determine if the user already exists or not. A user exists if they are known to to the user mapper.
177 ## <a name="ObjectMethod <strong>eachUser</strong> () - TWi"></a> [[ObjectMethod]] **eachUser** `() -> TWiki::IteratorofcUIDs`
179 Get an iterator over the list of all the registered users **not** including groups.
181 list of canonical\_ids ???
185 my $iterator = $umm->eachUser();
186 while ($iterator->hasNext()) {
187 my $user = $iterator->next();
191 ## <a name="ObjectMethod <strong>eachGroup</strong> () - TW"></a> [[ObjectMethod]] **eachGroup** `() -> TWiki::ListIteratorofgroupnames`
193 Get an iterator over the list of all the groups.
195 ## <a name="ObjectMethod <strong>each_GroupMember*"></a><a name="ObjectMethod *each_GroupMember</strong> "></a> [[ObjectMethod]] **eachGroupMember** `($group) -> $iterator`
197 Return a iterator of user ids that are members of this group. Should only be called on groups.
199 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.
201 ## <a name="ObjectMethod <strong>isGroup</strong> ($name) -"></a> [[ObjectMethod]] **isGroup** `($name) -> boolean`
203 Establish if a $name 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.
205 ## <a name="ObjectMethod <strong>is_InGroup</strong> ($cUID"></a> [[ObjectMethod]] **isInGroup** `($cUID,$group) -> $boolean`
207 Test if the user identified by $cUID is in the given group.
209 ## <a name="ObjectMethod <strong>eachMembership</strong> ($"></a> [[ObjectMethod]] **eachMembership** `($cUID) -> $iterator`
211 Return an iterator over the groups that $cUID is a member of.
213 ## <a name="ObjectMethod <strong>checkLogin</strong> ($logi"></a> [[ObjectMethod]] **checkLogin** `($login,$passwordU) -> $boolean`
215 Finds if the password is valid for the given user. This method is called using the login name rather than the $cUID so that it can be called with a user who can be authenticated, but may not be mappable to a cUID (yet).
217 Returns 1 on success, undef on failure.
219 TODO: add special check for [[BaseMapping]] admin user's login, and if its there (and we're in sudo\_context?) use that..
221 ## <a name="ObjectMethod <strong>setPassword</strong> ($cUI"></a> [[ObjectMethod]] **setPassword** `($cUID,$newPassU,$oldPassU) -> $boolean`
223 If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
225 If $oldPassU is not correct and not 1, will return 0.
227 If $oldPassU is 1, will force the change irrespective of the existing password, adding the user if necessary.
229 Otherwise returns 1 on success, undef on failure.
231 ## <a name="ObjectMethod <strong>passwordError</strong> ()"></a><a name="ObjectMethod <strong>passwordError</strong> () "></a> [[ObjectMethod]] **passwordError** `() -> $string`
233 Returns a string indicating the error that happened in the password handlers TODO: these delayed error's should be replaced with Exceptions.
235 returns undef if no error
237 ## <a name="ObjectMethod <strong>removeUser</strong> ($cUID"></a> [[ObjectMethod]] **removeUser** `($cUID) -> $boolean`
239 Delete the users entry. Removes the user from the password manager and user mapping manager. Does **not** remove their personal topics, which may still be linked.