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.