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