internal package
Foswiki::Users
On this page:
- internal package Foswiki::Users
- ClassMethod new ($session)
- ObjectMethod loadSession()
- ObjectMethod finish()
- ObjectMethod loginTemplateName () → templateFile
- ObjectMethod supportsRegistration () → boolean
- ObjectMethod validateRegistrationField ( $field, $value ) → text
- ObjectMethod initialiseUser ($login) → $cUID
- randomPassword()
- ObjectMethod addUser($login, $wikiname, $password, $emails) → $cUID
- StaticMethod mapLogin2cUID( $login ) → $cUID
- ObjectMethod getCGISession()
- ObjectMethod getLoginManager() → $loginManager
- ObjectMethod getCanonicalUserID( $identifier ) → $cUID
- ObjectMethod findUserByWikiName( $wn ) → \@users
- ObjectMethod findUserByEmail( $email ) → \@users
- ObjectMethod getEmails($name) → @emailAddress
- ObjectMethod setEmails($cUID, @emails)
- ObjectMethod isAdmin( $cUID ) → $boolean
- ObjectMethod isInUserList( $cUID, \@list ) → $boolean
- ObjectMethod getLoginName($cUID) → $login
- ObjectMethod getWikiName($cUID) → $wikiName
- ObjectMethod webDotWikiName($cUID) → $webDotWiki
- ObjectMethod userExists($cUID) → $boolean
- ObjectMethod userExistsInLDAP($cUID) → $boolean
- ObjectMethod userExistsInLDAP($cUID) → $boolean
- ObjectMethod eachUser() → Foswiki::Iterator of cUIDs
- ObjectMethod eachGroup() → $iterator
- ObjectMethod eachGroupMember($group) → $iterator
- ObjectMethod isGroup($name) → boolean
- ObjectMethod isInGroup( $cUID, $group, $options) → $boolean
- ObjectMethod eachMembership($cUID) → $iterator
- ObjectMethod groupAllowsView($group) → boolean
- ObjectMethod groupAllowsChange($group, $cuid) → boolean
- ObjectMethod addToGroup( $cuid, $group, $create ) → $boolean
- ObjectMethod removeFromGroup( $cuid, $group ) → $boolean
- ObjectMethod checkLogin( $login, $passwordU ) → $boolean
- ObjectMethod setPassword( $cUID, $newPassU, $oldPassU ) → $boolean
- ObjectMethod passwordError($cUID) → $string
- ObjectMethod removeUser( $cUID ) → $boolean
internal package
Foswiki::Users
This package provides services for the lookup and manipulation of login and
wiki names of users, and their authentication.
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.
Foswiki 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.
Using this module (and the associated plug-in user mapper) Foswiki 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.
Internally in the code Foswiki 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.
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.
Terminology
- A login name is the name used to log in to Foswiki. Each login name is assumed to be unique to a human. The Password module is responsible for authenticating and manipulating login names.
- A canonical user id is an internal Foswiki representation of a user. Each canonical user id maps 1:1 to a login name.
- 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.
- 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.
- An email is an email address asscoiated with a login name. A single login name may have many emails.
NOTE:
- wherever the code references $cUID, its a canonical_id
- wherever the code references $group, its a group_name
- $name may be a group or a cUID
ClassMethod
new ($session)
Construct the user management object that is the facade to the
BaseUserMapping
and the user mapping chosen in the configuration.
ObjectMethod
loadSession()
Setup the cgi session, from a cookie or the url. this may return
the login, but even if it does, plugins will get the chance to
override (in Foswiki.pm)
ObjectMethod
finish()
Break circular references.
ObjectMethod
loginTemplateName () → templateFile
allows
UserMappings to come with customised login screens - that should preffereably only over-ride the UI function
ObjectMethod
supportsRegistration () → boolean
#return 1 if the main
UserMapper supports registration (ie can create new users)
ObjectMethod
validateRegistrationField ( $field, $value ) → text
Return the registration formfield sanitized by the mapper, or oops thrown to block the registration.
ObjectMethod
initialiseUser ($login) → $cUID
Given a login (which must have been authenticated) determine the cUID that
corresponds to that user. This method is used from Foswiki.pm to map the
$REMOTE_USER to a cUID.
randomPassword()
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.
ObjectMethod
addUser($login, $wikiname, $password, $emails) → $cUID
-
$login
- user login name. If undef
, $wikiname
will be used as the login name.
-
$wikiname
- user wikiname. If undef
, the user mapper will be asked to provide it.
-
$password
- password. If undef, a password will be generated.
Add a new Foswiki user identity, returning the canonical user id for the new
user. Used ONLY for user registration.
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.
$login can be undef; $wikiname must always have a value.
The return value is the canonical user id that is used
by Foswiki to identify the user.
StaticMethod
mapLogin2cUID( $login ) → $cUID
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.
This static function is designed to be called from custom user mappers that
support 1:1 login-to-cUID mappings.
ObjectMethod
getCGISession()
Get the currect CGI session object
ObjectMethod
getLoginManager() → $loginManager
Get the
Foswiki::LoginManager object associated with this session, if there is
one. May return undef.
ObjectMethod
getCanonicalUserID( $identifier ) → $cUID
Works out the Foswiki canonical user identifier for the user who either
(1) logs in with the login name $identifier or (2) has the wikiname
$identifier.
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.
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.
Returns undef if the user does not exist.
ObjectMethod
findUserByWikiName( $wn ) → \@users
-
$wn
- wikiname to look up
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.
If $wn is the name of a group, the group will
not be expanded.
ObjectMethod
findUserByEmail( $email ) → \@users
-
$email
- email address to look up
Return a list of canonical user names for the users that have this email
registered with the user mapping managers.
ObjectMethod
getEmails($name) → @emailAddress
If $name is a cUID, 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)
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.
ObjectMethod
isAdmin( $cUID ) → $boolean
True if the user is an admin
- is $Foswiki::cfg{SuperAdminGroup}
- is a member of the $Foswiki::cfg{SuperAdminGroup}
- Foswiki is bootstrapping a new configuration
ObjectMethod
isInUserList( $cUID, \@list ) → $boolean
Return true if $cUID is in a list of user
wikinames,
logins and group ids.
The list may contain the conventional web specifiers (which are ignored).
ObjectMethod
getLoginName($cUID) → $login
Get the login name of a user. Returns undef if the user is not known.
ObjectMethod
getWikiName($cUID) → $wikiName
Get the wikiname to display for a canonical user identifier.
Can return undef if the user is not in the mapping system
(or the special case from initialiseUser)
ObjectMethod
webDotWikiName($cUID) → $webDotWiki
Return the fully qualified wikiname of the user
ObjectMethod
userExists($cUID) → $boolean
Determine if the user already exists or not. A user exists if they are
known to to the user mapper.
ObjectMethod
userExistsInLDAP($cUID) → $boolean
Determine if the user already exists in LDAP or not.
ObjectMethod
userExistsInLDAP($cUID) → $boolean
Determine if the user already exists in LDAP or not.
ObjectMethod
eachUser() → Foswiki::Iterator of cUIDs
Get an iterator over the list of all the registered users
not including
groups.
list of canonical_ids ???
Use it as follows:
my $iterator = $umm->eachUser();
while ($iterator->hasNext()) {
my $user = $iterator->next();
...
}
ObjectMethod
eachGroup() → $iterator
Get an iterator over the list of all the group names.
ObjectMethod
eachGroupMember($group) → $iterator
Return a iterator of user ids that are members of this group.
Should only be called on groups.
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.
ObjectMethod
isGroup($name) → boolean
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.
ObjectMethod
isInGroup( $cUID, $group, $options) → $boolean
Test if the user identified by $cUID is in the given group. Options
is a hash array of options effecting the search. Available options are:
-
expand => 1
0/1 - should nested groups be expanded when searching for the user. Default is 1, to expand nested groups.
ObjectMethod
eachMembership($cUID) → $iterator
Return an iterator over the groups that $cUID
is a member of.
ObjectMethod
groupAllowsView($group) → boolean
returns 1 if the group is able to be modified by the current logged in user
ObjectMethod
groupAllowsChange($group, $cuid) → boolean
returns 1 if the group is able to be modified by the current logged in user
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.
ObjectMethod
removeFromGroup( $cuid, $group ) → $boolean
ObjectMethod
checkLogin( $login, $passwordU ) → $boolean
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).
Returns 1 on success, undef on failure.
TODO: add special check for
BaseMapping admin user's login, and if
its there (and we're in sudo_context?) use that..
ObjectMethod
setPassword( $cUID, $newPassU, $oldPassU ) → $boolean
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($cUID) → $string
Returns a string indicating the error that happened in the password handler
The cUID is used to determine which mapper is handling the user. If called
without a cUID, then the Base mapping is used.
TODO: these delayed error's should be replaced with Exceptions.
returns undef if no 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.