| Package TWiki::Users::TWikiUserMapping
The User mapping is the process by which TWiki maps from a username (a login name)
to a wikiname and back. It is also where groups are defined.
By default TWiki maintains user topics and group topics in the Main that
define users and group. These topics are
- TWikiUsers - stores a mapping from usernames to TWiki names
- WikiName - for each user, stores info about the user
- GroupNameGroup - for each group, a topic ending with "Group" stores a list of users who are part of that group.
Many sites will want to override this behaviour, for example to get users and groups from a corporate database.
This class implements the basic TWiki behaviour using topics to store users,
but is also designed to be subclassed so that other services can be used.
Subclasses should be named 'XxxxUserMapping' so that configure can find them.
On this page:
- ClassMethod new ($session,$impl)
- ObjectMethod finish ()
- ObjectMethod supportsRegistration () -> false
- ObjectMethod handlesUser ($cUID,$login,$wikiname) -> $boolean
- ObjectMethod login2cUID ($login,$dontcheck) -> $cUID
- ObjectMethod getLoginName ($cUID) -> login
- ObjectMethod addUser ($login,$wikiname,$password,$emails,$mcp) -> $cUID
- ObjectMethod removeUser ($cUID) -> $boolean
- ObjectMethod getWikiName ($cUID) -> $wikiname
- ObjectMethod userExists ($cUID) -> $boolean
- ObjectMethod eachUser () -> TWiki::ListIteratorofcUIDs
- ObjectMethod eachGroupMember ($group) -> listIteratorofcUIDs
- ObjectMethod isGroup ($user) -> boolean
- ObjectMethod eachGroup () -> ListIteratorofgroupnames
- ObjectMethod eachMembership ($cUID) -> ListIteratorofgroupsthisuserisin
- ObjectMethod isAdmin ($cUID) -> $boolean
- ObjectMethod findUserByEmail ($email) -> \@cUIDs
- ObjectMethod getEmails ($name) -> @emailAddress
- ObjectMethod setEmails ($cUID,@emails) -> boolean
- StaticMethod mapper_getEmails ($session,$user)
- StaticMethod mapper_setEmails ($session,$user,@emails)
- ObjectMethod getMustChangePassword ($cUID) -> $flag
- ObjectMethod getUserData ($cUID) -> $dataRef
- ObjectMethod setUserData ($cUID,$dataRef)
- ObjectMethod findUserByWikiName ($wikiname) -> listofcUIDsassociatedwiththatwikiname
- ObjectMethod checkPassword ($login,$password) -> $boolean
- ObjectMethod setPassword ($cUID,$newPassU,$oldPassU,$mcp) -> $boolean
- ObjectMethod passwordError () -> $string
Constructs a new user mapping handler of this type, referring to $session
for any required TWiki services.
Break circular references.
ObjectMethod supportsRegistration () -> false
return 1 if the UserMapper supports registration (ie can create new users)
ObjectMethod handlesUser ($cUID,$login,$wikiname) -> $boolean
Called by the TWiki::Users object to determine which loaded mapping
to use for a given user.
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. This mapping is special - for backwards
compatibility, it assumes responsibility for all non BaseMapping users.
If you're needing to mix the TWikiuserMapping with other mappings,
define $this->{mapping_id} = 'TWikiUserMapping_';
ObjectMethod login2cUID ($login,$dontcheck) -> $cUID
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 correspond 1:1 to the login name.
(undef on failure)
(if dontcheck is true, return a cUID for a nonexistant user too.
This is used for registration)
ObjectMethod getLoginName ($cUID) -> login
Converts an internal cUID to that user's login
(undef on failure)
ObjectMethod addUser ($login,$wikiname,$password,$emails,$mcp) -> $cUID
throws an Error::Simple
Add a user to the persistant mapping that maps from usernames to wikinames
and vice-versa. The default implementation uses a special topic called
"TWikiUsers" in the users web. Subclasses will provide other implementations
(usually stubs if they have other ways of mapping usernames to wikinames).
Names 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.
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.
if you fail to create a new user (for eg your Mapper has read only access),
throw Error::Simple(
'Failed to add user: '.$ph->error());
ObjectMethod removeUser ($cUID) -> $boolean
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.
ObjectMethod getWikiName ($cUID) -> $wikiname
Map a canonical user name to a wikiname. If it fails to find a
WikiName, it will attempt to find a matching loginname, and use
an escaped version of that.
If there is no matching WikiName or LoginName, it returns undef.
ObjectMethod userExists ($cUID) -> $boolean
Determine if the user already exists or not. Whether a user exists
or not is determined by the password manager.
ObjectMethod eachUser () -> TWiki::ListIteratorofcUIDs
See baseclass for documentation
ObjectMethod eachGroupMember ($group) -> listIteratorofcUIDs
See baseclass for documentation
ObjectMethod isGroup ($user) -> boolean
See baseclass for documentation
See baseclass for documentation
See baseclass for documentation
ObjectMethod isAdmin ($cUID) -> $boolean
True if the user is an admin
- is $TWiki::cfg{SuperAdminGroup}
- is a member of the $TWiki::cfg{SuperAdminGroup}
ObjectMethod findUserByEmail ($email) -> \@cUIDs
-
$email - email address to look up
Return a list of canonical user names for the users that have this email
registered with the password manager or the user mapping manager.
The password manager is asked first for whether it maps emails.
If it doesn't, then the user mapping manager is asked instead.
If $name is a user, return their email addresses. If it is a group,
return the addresses of everyone in the group.
The password manager and user mapping manager are both consulted for emails
for each user (where they are actually found is implementation defined).
Duplicates are removed from the list.
ObjectMethod setEmails ($cUID,@emails) -> boolean
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.
StaticMethod mapper_getEmails ($session,$user)
Only used if passwordManager->isManagingEmails= = =false
(The emails are stored in the user topics.
Note: This method is PUBLIC because it is used by the tools/upgrade_emails.pl
script, which needs to kick down to the mapper to retrieve email addresses
from TWiki topics.
StaticMethod mapper_setEmails ($session,$user,@emails)
Only used if passwordManager->isManagingEmails = false .
(emails are stored in user topics
ObjectMethod getMustChangePassword ($cUID) -> $flag
Returns 1 if the $cUID must change the password, else 0. Returns undef if $cUID not found.
ObjectMethod getUserData ($cUID) -> $dataRef
Return a reference to an array of hashes with user data, used to manage
users. Each item is a hash with:
-
{name} - name of field, such as "email"
-
{title} - title of field, such as "E-mail"
-
{value} - value of field, such as "jimmy@example.com"
-
{type} - type of field: text , password , checkbox , label
-
{size} - size of field, such as 40
-
{note} - comment note, if any
User management forms can be build dynamically from this data structure.
Each password manager may return a different set of fields.
ObjectMethod setUserData ($cUID,$dataRef)
Set the user data of a user. Same array of hashes as getUserData is
assumed, although only {name} and {value} are used.
ObjectMethod findUserByWikiName ($wikiname) -> listofcUIDsassociatedwiththatwikiname
See baseclass for documentation
The $skipExistanceCheck parameter
is private to this module, and blocks the standard existence check
to avoid reading .htpasswd when checking group memberships).
ObjectMethod checkPassword ($login,$password) -> $boolean
Finds if the password is valid for the given user.
Returns 1 on success, undef on failure.
ObjectMethod setPassword ($cUID,$newPassU,$oldPassU,$mcp) -> $boolean
BEWARE: $user should be a cUID, but is a login when the resetPassword
functionality is used.
The UserMapper needs to convert either one to a valid login for use by
the Password manager
TODO: needs fixing
If the $oldPassU matches matches the user's password, then it will
replace it with $newPassU.
If $oldPassU is not correct and not 1, will return 0.
If $oldPassU is 1, will force the change irrespective of
the existing password, adding the user if necessary.
Otherwise returns 1 on success, undef on failure.
ObjectMethod passwordError () -> $string
returns a string indicating the error that happened in the password handlers
TODO: these delayed error's should be replaced with Exceptions.
returns undef if no error
|