PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

internal package Foswiki::Users::TopicUserMapping @isa Foswiki::UserMapping'); is a Foswiki::UserMapping

use

The User mapping is the process by which Foswiki maps from a username (a login name) to a wikiname and back. It is also where groups are defined.

By default Foswiki maintains user topics and group topics in the Main that define users and group. These topics are

• WikiUsers - stores a mapping from usernames to Wiki 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 Foswiki 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.

ClassMethod new ($session, $impl)

Constructs a new user mapping handler of this type, referring to $session for any required Foswiki services.

ObjectMethod finish()

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 Foswiki::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 TopicUserMapping with other mappings, define $this->{mapping_id} = 'TopicUserMapping_';

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) → $cUID

throws an Error::Simple

Add a user to the persistent mapping that maps from usernames to wikinames and vice-versa. The default implementation uses a special topic called "WikiUsers" 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 $Foswiki::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 _maintainUsersTopic ( $action, $login, $wikiname )

throws an Error::Simple

Add or remove a user to/from the persistent mapping that maps from usernames to wikinames and vice-versa. The default implementation uses a special topic called "WikiUsers" in the users web. =cut

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.

Note that this must be called with the cUID. If any doubt, resolve the cUID by $this->{session}->{users}->getCanonicalUserID($identity).

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 () → Foswiki::Iterator of cUIDs

See baseclass for documentation

ObjectMethod eachGroupMember ($group) → listIterator of cUIDs

See baseclass for documentation

ObjectMethod isGroup ($user) → boolean

See baseclass for documentation

ObjectMethod eachGroup () → ListIterator of groupnames

See baseclass for documentation

ObjectMethod eachMembership ($cUID) → ListIterator of groups this user is in

See baseclass for documentation

ObjectMethod groupAllowsView($group) → boolean

returns 1 if the group is able to be viewed by the current logged in user

implemented using topic VIEW permissions

ObjectMethod groupAllowsChange($group, $cuid) → boolean

returns 1 if the group is able to be modified by $cuid

implemented using topic CHANGE permissions

ObjectMethod addToGroup( $cuid, $group, $create ) → $boolean

adds the user specified by the cuid to the group. If the group does not exist, it will return false and do nothing, unless the create flag is set.

cuid be a groupname which is added like it was an unknown user

ObjectMethod removeFromGroup( $cuid, $group ) → $boolean

ObjectMethod _clearGroupCache( $groupName )

Removes the cache entries for unexpanded and expanded groups, and searches un-expanded groups for any nesting group references clearing them as well.

Note: This is not recursive and does not attempt to handle more than one level of nested groups.

ObjectMethod isAdmin( $cUID ) → $boolean

True if the user is an admin

• is $Foswiki::cfg{SuperAdminGroup}
• is a member of the $Foswiki::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.

ObjectMethod getEmails($name) → @emailAddress

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 or $Foswiki::cfg{TopicUserMapping}{ForceManageEmails} is enabled. (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 Wiki topics.

StaticMethod mapper_setEmails ($session, $user, @emails)

Only used if passwordManager->isManagingEmails = false or $Foswiki::cfg{TopicUserMapping}{ForceManageEmails} is enabled. (emails are stored in user topics

ObjectMethod findUserByWikiName ($wikiname) → list of cUIDs associated with that wikiname

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 ) → $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

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

returns undef if no error

ObjectMethod validateRegistrationField($field, $value ) → $string

This method is called for every field submitted during registration. It is also used to validate the username when adding a member to a group.

Returns a string containing the sanitized registration field, or can throw an Error::Simple if the field contains illegal data to block the registration.

returns the string unchanged if no issue found.