data/TWiki/TWikiUsersDotPm.txt
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiUsersDotPm.txt	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,337 @@
     1.4 +---+ Package =TWiki::Users=
     1.5 +This package provides services for the lookup and manipulation of login and
     1.6 +wiki names of users, and their authentication.
     1.7 +
     1.8 +It is a Facade that presents a common interface to the User Mapping
     1.9 +and Password modules. The rest of the core should *only* use the methods
    1.10 +of this package, and should *never* call the mapping or password managers
    1.11 +directly.
    1.12 +
    1.13 +TWiki uses the concept of a _login name_ which is used to authenticate a
    1.14 +user. A login name maps to a _wiki name_ that is used to identify the user
    1.15 +for display. Each login name is unique to a single user, though several
    1.16 +login names may map to the same wiki name.
    1.17 +
    1.18 +Using this module (and the associated plug-in user mapper) TWiki supports
    1.19 +the concept of _groups_. Groups are sets of login names that are treated
    1.20 +equally for the purposes of access control. Group names do not have to be
    1.21 +wiki names, though it is helpful for display if they are.
    1.22 +
    1.23 +Internally in the code TWiki uses something referred to as a _canonical user
    1.24 +id_ or just _user id_. The user id is also used externally to uniquely identify
    1.25 +the user when (for example) recording topic histories. The user id is *usually*
    1.26 +just the login name, but it doesn't need to be. It just has to be a unique
    1.27 +7-bit alphanumeric and underscore string that can be mapped to/from login
    1.28 +and wiki names by the user mapper.
    1.29 +
    1.30 +The canonical user id should *never* be seen by a user. On the other hand,
    1.31 +core code should never use anything *but* a canonical user id to refer
    1.32 +to a user.
    1.33 +
    1.34 +*Terminology*
    1.35 +   * A *login name* is the name used to log in to TWiki. Each login name is
    1.36 +     assumed to be unique to a human. The Password module is responsible for
    1.37 +     authenticating and manipulating login names.
    1.38 +   * A *canonical user id* is an internal TWiki representation of a user. Each
    1.39 +     canonical user id maps 1:1 to a login name.
    1.40 +   * A *wikiname* is how a user is displayed. Many user ids may map to a
    1.41 +     single wikiname. The user mapping module is responsible for mapping
    1.42 +     the user id to a wikiname.
    1.43 +   * A *group id* represents a group of users and other groups.
    1.44 +     The user mapping module is responsible for mapping from a group id to
    1.45 +     a list of canonical user ids for the users in that group.
    1.46 +   * An *email* is an email address asscoiated with a *login name*. A single
    1.47 +     login name may have many emails.
    1.48 +	 
    1.49 +*NOTE:* 
    1.50 +   * wherever the code references $user, its a canonical_id
    1.51 +   * wherever the code references $group, its a group_name
    1.52 +
    1.53 +
    1.54 +%TOC%
    1.55 +
    1.56 +---++ ClassMethod *new* <tt>($session)</tt>
    1.57 +Construct the user management object that is the facade to the BaseUserMapping
    1.58 +and the user mapping chosen in the configuration.
    1.59 +
    1.60 +
    1.61 +
    1.62 +---++ ObjectMethod *finish* <tt>()</tt>
    1.63 +Break circular references.
    1.64 +
    1.65 +
    1.66 +
    1.67 +---++ ObjectMethod *loginTemplateName* <tt>() -> templateFile</tt>
    1.68 +
    1.69 +allows UserMappings to come with customised login screens - that should preffereably only over-ride the UI function
    1.70 +
    1.71 +
    1.72 +
    1.73 +---++ ObjectMethod *supportsRegistration* <tt>() -> boolean</tt>
    1.74 +
    1.75 +#return 1 if the  main UserMapper supports registration (ie can create new users)
    1.76 +
    1.77 +
    1.78 +
    1.79 +---++ ObjectMethod *initialiseUser* <tt>($login) -> cUID</tt>
    1.80 +
    1.81 +
    1.82 +
    1.83 +
    1.84 +
    1.85 +---++ randomPassword()
    1.86 +Static function that returns a random password
    1.87 +
    1.88 +
    1.89 +---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> $cUID</tt>
    1.90 +
    1.91 +   * =$login= - user login name. If =undef=, =$wikiname= will be used as the login name.
    1.92 +   * =$wikiname= - user wikiname. If =undef=, the user mapper will be asked
    1.93 +     to provide it.
    1.94 +   * =$password= - password. If undef, a password will be generated.
    1.95 +
    1.96 +Add a new TWiki user identity, returning the canonical user id for the new
    1.97 +user. Used ONLY for user registration.
    1.98 +
    1.99 +The user is added to the password system (if there is one, and if it accepts
   1.100 +changes). If the user already exists in the password system, then the password
   1.101 +is checked and an exception thrown if it doesn't match. If there is no
   1.102 +existing user, and no password is given, a random password is generated.
   1.103 +
   1.104 +$login can be undef; $wikiname must always have a value.
   1.105 +
   1.106 +The return value is the canonical user id that is used
   1.107 +by TWiki to identify the user.
   1.108 +
   1.109 +
   1.110 +
   1.111 +---++ StaticMethod *forceCUID* <tt>($cUID) -> $cUID</tt>
   1.112 +
   1.113 +This function ensures that any cUID's are able to be used for rcs, and other internals
   1.114 +not capable of coping with user identifications that contain more than 7 bit ascii.
   1.115 +
   1.116 +repeated calls must result in the same result (sorry, can't spell the word for it)so the '_' must not be re-encoded
   1.117 +
   1.118 +Please, call this function in any custom Usermapper to simplifyyour mapping code.
   1.119 +
   1.120 +
   1.121 +
   1.122 +---++ ObjectMethod *getCanonicalUserID* <tt>($login) -> $user</tt>
   1.123 +
   1.124 +Works out the unique TWiki identifier for the user who logs in with the
   1.125 +given login. The canonical user ID is an alphanumeric string that is unique
   1.126 +to the login name, and can be mapped back to a login name and the
   1.127 +corresponding wiki name using the methods of this class.
   1.128 +
   1.129 +returns undef if the user does not exist.
   1.130 +
   1.131 +
   1.132 +
   1.133 +---++ ObjectMethod *findUserByWikiName* <tt>($wn) -> \@users</tt>
   1.134 +   * =$wn= - wikiname to look up
   1.135 +Return a list of canonical user names for the users that have this wikiname.
   1.136 +Since a single wikiname might be used by multiple login ids, we need a list.
   1.137 +
   1.138 +If $wn is the name of a group, the group will *not* be expanded.
   1.139 +
   1.140 +
   1.141 +
   1.142 +---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
   1.143 +   * =$email= - email address to look up
   1.144 +Return a list of canonical user names for the users that have this email
   1.145 +registered with the user mapping managers.
   1.146 +
   1.147 +
   1.148 +
   1.149 +---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>
   1.150 +
   1.151 +If this is a user, return their email addresses. If it is a group,
   1.152 +return the addresses of everyone in the group.
   1.153 +
   1.154 +The password manager and user mapping manager are both consulted for emails
   1.155 +for each user (where they are actually found is implementation defined).
   1.156 +
   1.157 +Duplicates are removed from the list.
   1.158 +
   1.159 +
   1.160 +
   1.161 +---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>
   1.162 +
   1.163 +Set the email address(es) for the given user.
   1.164 +The password manager is tried first, and if it doesn't want to know the
   1.165 +user mapping manager is tried.
   1.166 +
   1.167 +
   1.168 +
   1.169 +---++ ObjectMethod *isAdmin* <tt>($cUID) -> $boolean</tt>
   1.170 +
   1.171 +True if the user is an admin
   1.172 +   * is $TWiki::cfg{SuperAdminGroup}
   1.173 +   * is a member of the $TWiki::cfg{SuperAdminGroup}
   1.174 +
   1.175 +
   1.176 +
   1.177 +---++ ObjectMethod *isInList* <tt>($user,$list) -> $boolean</tt>
   1.178 +
   1.179 +Return true if $user is in a list of user *wikinames* and group ids.
   1.180 +
   1.181 +$list is a comma-separated wikiname and group list. The list may contain the
   1.182 +conventional web specifiers (which are ignored).
   1.183 +
   1.184 +
   1.185 +
   1.186 +---++ ObjectMethod *getLoginName* <tt>($cUID) -> $string</tt>
   1.187 +
   1.188 +Get the login name of a user.
   1.189 +
   1.190 +
   1.191 +
   1.192 +---++ ObjectMethod *getWikiName* <tt>($cUID) -> $wikiName</tt>
   1.193 +Get the wikiname to display for a canonical user identifier.
   1.194 +
   1.195 +can return undef if the user is not in the mapping system
   1.196 +(or the special case from initialiseUser)
   1.197 +
   1.198 +
   1.199 +
   1.200 +---++ ObjectMethod *webDotWikiName* <tt>($user) -> $webDotWiki</tt>
   1.201 +
   1.202 +Return the fully qualified wikiname of the user
   1.203 +
   1.204 +
   1.205 +
   1.206 +---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
   1.207 +
   1.208 +Determine if the user already exists or not. A user exists if they are
   1.209 +known to to the user mapper.
   1.210 +
   1.211 +
   1.212 +
   1.213 +---++ ObjectMethod *eachUser* <tt>() -> $iterator</tt>
   1.214 +
   1.215 +Get an iterator over the list of all the registered users *not* including
   1.216 +groups.
   1.217 +
   1.218 +list of canonical_ids ???
   1.219 +
   1.220 +Use it as follows:
   1.221 +<verbatim>
   1.222 +    my $iterator = $umm->eachUser();
   1.223 +    while ($iterator->hasNext()) {
   1.224 +        my $user = $iterator->next();
   1.225 +        ...
   1.226 +    }
   1.227 +</verbatim>
   1.228 +
   1.229 +
   1.230 +
   1.231 +---++ ObjectMethod *eachGroup* <tt>() -> $iterator</tt>
   1.232 +
   1.233 +Get an iterator over the list of all the groups.
   1.234 +
   1.235 +
   1.236 +
   1.237 +---++ ObjectMethod *eachGroupMember* <tt>($group) -> $iterator</tt>
   1.238 +
   1.239 +Return a iterator of user ids that are members of this group.
   1.240 +Should only be called on groups.
   1.241 +
   1.242 +Note that groups may be defined recursively, so a group may contain other
   1.243 +groups. This method should *only* return users i.e. all contained groups
   1.244 +should be fully expanded.
   1.245 +
   1.246 +
   1.247 +
   1.248 +---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
   1.249 +
   1.250 +Establish if a user refers to a group or not.
   1.251 +
   1.252 +The default implementation is to check if the wikiname of the user ends with
   1.253 +'Group'. Subclasses may override this behaviour to provide alternative
   1.254 +interpretations. The $TWiki::cfg{SuperAdminGroup} is recognized as a
   1.255 +group no matter what it's name is.
   1.256 +
   1.257 +QUESTION: is the $user parameter here a string, or a canonical_id??
   1.258 +
   1.259 +
   1.260 +
   1.261 +---++ ObjectMethod *isInGroup* <tt>($user,$group) -> $boolean</tt>
   1.262 +
   1.263 +Test if user is in the given group.
   1.264 +
   1.265 +
   1.266 +
   1.267 +---++ ObjectMethod *eachMembership* <tt>($cUID) -> $iterator</tt>
   1.268 +
   1.269 +Return an iterator over the groups that $cUID
   1.270 +is a member of.
   1.271 +
   1.272 +
   1.273 +
   1.274 +---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
   1.275 +
   1.276 +Finds if the password is valid for the given user.
   1.277 +
   1.278 +Returns 1 on success, undef on failure.
   1.279 +
   1.280 +TODO: add special check for BaseMapping admin user's login, and if its there (and we're in sudo_context?) use that..
   1.281 +
   1.282 +
   1.283 +
   1.284 +---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
   1.285 +
   1.286 +If the $oldPassU matches matches the user's password, then it will
   1.287 +replace it with $newPassU.
   1.288 +
   1.289 +If $oldPassU is not correct and not 1, will return 0.
   1.290 +
   1.291 +If $oldPassU is 1, will force the change irrespective of
   1.292 +the existing password, adding the user if necessary.
   1.293 +
   1.294 +Otherwise returns 1 on success, undef on failure.
   1.295 +
   1.296 +
   1.297 +
   1.298 +---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
   1.299 +
   1.300 +returns a string indicating the error that happened in the password handlers
   1.301 +TODO: these delayed error's should be replaced with Exceptions.
   1.302 +
   1.303 +returns undef if no error
   1.304 +
   1.305 +
   1.306 +
   1.307 +---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
   1.308 +
   1.309 +Delete the users entry. Removes the user from the password
   1.310 +manager and user mapping manager. Does *not* remove their personal
   1.311 +topics, which may still be linked.
   1.312 +
   1.313 +
   1.314 +
   1.315 +---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>
   1.316 +
   1.317 +used for debugging to ensure we are actually passing a canonical_id
   1.318 +
   1.319 +These ASSERTS have been disabled, as they have been made dangerous and misleading
   1.320 +due to the legacy cUID code
   1.321 +
   1.322 +
   1.323 +
   1.324 +---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>
   1.325 +
   1.326 +used for debugging to ensure we are actually passing a user login
   1.327 +
   1.328 +These ASSERTS have been disabled, as they have been made dangerous and misleading
   1.329 +due to the legacy cUID code
   1.330 +
   1.331 +
   1.332 +
   1.333 +---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>
   1.334 +
   1.335 +used for debugging to ensure we are actually passing a user display_name (commonly a WikiWord Name)
   1.336 +
   1.337 +These ASSERTS have been disabled, as they have been made dangerous and misleading
   1.338 +due to the legacy cUID code
   1.339 +
   1.340 +