NAME
CGI::Builder::Auth::Context - Encapsulate an authentication context for an application
DESCRIPTION
The Class provides an API for manipulating the User and Group tables.
The context object keeps track of who the current user is and what groups that user belongs to. The username 'anonymous' is used to indicate that a user is not currently logged in. The name 'anonymous' is reserved and may not be used in the real user database.
When the context object is created, it checks the current session (if available) for an authentication token, and restores the context to its previous state based on this token. That is, it automatically logs in the user.
CLASS METHODS
Manipulate the User table ("htpasswd")
user_list
Returns a list of all users in the user table, as user objects.
add_user(\%attributes)
Adds the user to the table. Returns the user object on success, false on failure. Will fail if a user already exists with that name.
Required Attributes:
username
password
Additional, customizable attributes may be supported in a future release.
delete_user($user)
Deletes the named user from the table. The $user parameter may be a user object or a string containing the username. Returns true on success, false on failure.
Manipulate the Group table ("htgroup")
group_list
Returns a list of all groups in the group table, as group objects.
add_group('groupname')
Adds the group to the table. Returns the group object on success, false on failure. Will fail if a group already exists with that name.
delete_group($group)
Deletes the named group from the table. The $group parameter may be a group object or a string containing the groupname. Returns true on success, false on failure.
add_member($group,@users)
Make the @users members of the named $group. The $group parameter may be a group object or a string containing the groupname. The @users parameter may contain either user objects, strings containing usernames, or any combination. Returns true on success, false on failure.
remove_member($group,@users)
Remove the @users from the named $group (without removing the user account itself). The $group parameter may be a group object or a string containing the groupname. The @users parameter may contain either user objects, strings containing usernames, or any combination. Returns true on success, false on failure.
group_members($group)
Returns a list of all users who are members of the group. The list will contain user objects. The $group parameter may be a group object or a string containing the groupname.
INSTANCE (OBJECT) METHODS
user([$new_user])
Returns the current user for this context (your application). Optionally sets the current user to the value passed in $new_user, but normally you will use login to set the user instead, because login validates the password and then updates the session. This method does neither. If provided, $new_user must be a user object, not a string.
Defaults to the non-existent user 'anonymous'.
login('username','password')
If the password matches the one in the user database for the named user, sets the current user for this context, saves an authentication token to the current session (if available), and returns the user object. Otherwise, returns false and does not change the context nor the session.
logout
Sets the current user to the anonymous user, and removes the authentication token from the session (if available).
require_valid_user
Returns true if the current user for this context is a real user in the database (rather than the default anonymous user).
require_group(@groups)
Returns true if the current user is a member of at least one of the @groups. The @groups parameter may contain group objects, strings, or any combination.
require_user(@users)
Returns true if the current user is one of the @users. The @users parameter may contain either user objects, strings containing usernames, or any combination.
SUPPORT
Support for this module and all the modules of the CBF is via the mailing list. The list is used for general support on the use of the CBF, announcements, bug reports, patches, suggestions for improvements or new features. The API to the CBF is stable, but if you use the CBF in a production environment, it's probably a good idea to keep a watch on the list.
You can join the CBF mailing list at this url:
http://lists.sourceforge.net/lists/listinfo/cgi-builder-users
AUTHOR
Vincent Veselosky
COPYRIGHT AND LICENSE
Copyright 2004 by Vincent Veselosky
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.