/ 
CGI-Builder-Auth-0.06
River stage zero No dependents
/ CGI::Builder::Auth::RealmManager

NAME

CGI::Builder::Auth::RealmManager - Manage HTTPD server security realms

SYNOPSIS

    use CGI::Builder::Auth::RealmManager;

    # open up the database (could also use CGI::Builder::Auth::Realm::connect())
    $database = CGI::Builder::Auth::RealmManager->open(-config_file=>'/home/httpd/conf/realms.conf',
                                          -realm=>'members',
                                          -writable=>1);

    # List functions
    @users = $database->users();
    @groups = $database->groups();

    # Information about users and groups:
    print "Lincoln's groups are @group\n"
        if @group = $database->group(-user=>'lincoln');

    print "Lincoln is a subscriber\n" 
        if $database->match_group(-user=>'lincoln',-group=>'subscribers');

    print "Lincoln's password is $pass\n"
        if $pass = $database->passwd(-user=>'lincoln');

    print "Intruder alert.\n"
        unless $database->match_passwd(-user=>'lincoln',
                                       -password=>'xyzzy');

    $lincoln_info = $database->get_fields(-user=>'lincoln');
    print "Lincoln's full name is $lincoln_info->{Name}\n";

    print "The subscribers are @members.\n"
        if @members = $database->members(-group=>'subscribers');

    # Database updates
    print "Added Fred.\n"
        if $database->set_passwd(-user=>'fred',
                                 -password=>'sssh!',
                                 -fields=>{Name=>'Fred Smith',
                                           Nationality=>'French'});

    print "Assigned Fred to 'subscribers' and 'VIPs'\n"
	if $database->set_group(-user=>'fred',
                                -group=>['subscribers','VIPs']);

   print "Changed Fred's nationality.\n"
        if $database->set_fields(-user=>'fred',
                                 -fields=>{Nationality=>'German'});

    print "Fred is now gone.\n"
        if $database->delete_user(-user=>'fred');

    print "VIP group is now gone.\n"
        if $database->delete_group(-group=>'VIPs');

    print "Uh oh.  An error occurred: ",$database->errstr,"\n"
        if $database->errstr;

DESCRIPTION

Pay no attention to that man behind the curtain! Move along, nothing to see here!

This module was originally part of the HTTPD-User-Manage collection, which is available on CPAN. If you want to use it, go download that package. This module is used as part of the internal implementation of CGI::Builder::Auth. The original documentation is preserved here in this release for historical purposes. The software has been hacked and this documentation is not guaranteed to be correct. The module may disappear from the CGI::Builder::Auth distribution in a future release. Do not use it directly or rely on it.

CGI::Builder::Auth::RealmManager provides a high-level, unified view onto the many access control databases used by Apache, Netscape, NCSA httpd, CERN and other Web servers. It works hand-in-hand with CGI::Builder::Auth::Realm, which provides access to a standard configuration file for describing security database setups. Internally, CGI::Builder::Auth::Realm uses Doug MacEachern's HTTPD-Tools modules for database access and locking.

Important note: Do not use these modules to adjust the Unix password or group files. They do not have the same format as the Web access databases.

METHODS

CGI::Builder::Auth::RealmManager provides the following class and instance methods.

new()
$db = CGI::Builder::Auth::RealmManager->new(-realm    => $realm_def,
                               -writable => 1,
                               -mode     => 0644,
                               -server   => 'ncsa');

The new() class method creates a new connection to the database indicated by the indicated CGI::Builder::Auth::RealmDef object. Ordinarily it will be more convenient to use the open() method (below) or CGI::Builder::Auth::RealmDef::connect(). Only the -realm argument is mandatory. The others are optional and will default to reasonable values.

If successful, the function result is an CGI::Builder::Auth::RealmManager object, which you can treat as a handle to the database.

Arguments:

-realm      Realm definition.  See CGI::Builder::Auth::Realm(3).
-writable   If true, open database for writing.
-mode       Override file creation mode.
-server     Override server type.
open()
$db = CGI::Builder::Auth::RealmManager->open(-realm       => 'subscribers',
                                -config_file => '/home/httpd/conf/realms.conf',
                                -writable => 1,
                                -mode     => 0644,
                                -server   => 'ncsa');

The open() class method creates a new connection to the database given the indicated configuration file and realm name. Internally it first creates an CGI::Builder::Auth::Realm object, then queries it for the named realm, passing this result to new(). This is probably the easiest way to create a new connection.

Only the -realm and -config_file arguments are mandatory. The others are optional and will default to reasonable values.

If successful, the function result is an CGI::Builder::Auth::RealmManager object, which you can treat as a handle to the database.

Arguments:

-config_file Path to realm configuration file. See CGI::Builder::Auth::Realm(3).
-realm       Realm name.
-writable    If true, open database for writing.
-config      An alias for -config_file.
-mode        Override file creation mode.
-server      Override server type.
close()
$db->close()

When you are done with the database you should close() it. This will commit changes and tidy up.

users()
@users = $db->users();

Return all users known to this database as a (potentially very long) list.

groups()
@groups = $db->groups()

Return all groups known to this database as a (potentially very long) list.

group()
@groups = $db->group(-user=>'username');
$boolean = $db->group(-user=>'username',-group=>'groupname');

This method returns information about the groups that a user belongs to. Called with the name of the user only, it returns a list of all the groups the user is a member of. Called with both a user and a group name, it returns a boolean value indicating whether the user belongs to the group.

Arguments:

-user     Name of the user
-group    Name of the group
-name     An alias for -user
-grp      An alias for -group

You can also call this method with the positional parameters (user,group), as in:

@groups = $db->group('username');
match_group()
$boolean = $db->match_group(-user=>'username',-group=>'groupname');

This method is identical to the group() function, except that it requires a group name to be provided.

passwd()
$password = $db->passwd(-user=>'username');
$boolean = $db->passwd(-user=>'username',-password=>'password');

Called with a user name this method returns his encrypted password. Called with a user name and an unencrypted password, this routine returns a boolean indicating whether this password matches the stored password.

Arguments:

-user      Name of the user
-password  Password to check against (optional)
-name      Alias for -user
-passwd    Alias for -password

You can also call this routine using positional arguments, where the first argument is the user name and the second is the password to try:

print "You're OK" if $db->password('Fred','Open sesame');
password()
$password = $db->password(-user=>'username');
$boolean = $db->password(-user=>'username',-password=>'password');

An alias for passwd(), just to make things interesting.

match_passwd()
$boolean = $db->match_passwd(-user=>'username',-password=>'password');

This method is identical to the two-argument form of passwd(), except that it requires a trial password to be provided.

match()
$boolean = $db->match(-user=>'username',-password=>'password');

This method is an alias for match_passwd(), just to make things interesting.

get_fields()
$fields = $db->get_fields(-user=>'username',
                          -fields=>\@list_of_fields);

The user database can contain additional information about the user in the form of name/value pairs. This method provides access to these "additional fields."

get_fields() accepts a user name and optionally a list of the fields to retrieve. If no field list is provided, it will retrieve all fields defined in the security realm configuration file (see CGI::Builder::Auth::Realm (3)). In practice, it is rarely necessary to limit the fields that are retrieved unless you are accessing a SQL database table containing an unusually large number of fields.

Arguments:

-user    Name of user
-fields  List reference to fields to retrieve (optional)
-name    Alias for -user
-field   Alias for -fields

The return value is a hash reference. You can retrieve the actual values like this:

$fields = $db->get_fields(-user=>'fred');
print $fields->{'Full_Name'};
set_passwd()
$resultcode = $db->set_passwd(-user=>'username',
                              -password=>'password',
                              -fields=>\%extra_fields);

set_passwd() sets the user's password and/or additional field information. If the user does not already exist in the database, he is created. The method requires the username and one or more of the new password and a hash reference to additional user fields. If either the password or the additional fields are absent, they will be unchanged.

When setting field values, the old and new values are merged. To delete a previous field value, you must explicitly set it to undef in the hash reference. Otherwise the previous value will be retained.

A result code of true indicates a successful update. The method will fail unless the database is opened for writing.

Arguments:

-user      Name of the user to update
-password  New password
-fields    Hash ref to the fields to update
-name      Alias for -user
-passwd    Alias for -password
-gcos      Alias for -fields
set_password()
$resultcode = $db->set_password(-user=>'username',
                                -password=>'password',
                                -fields=>\%extra_fields);

This is an alias for set_passwd(), just to make life interesting.

set_fields()
$resultcode = $db->set_fields(-user=>'username',
                              -fields=>\%extra_fields);

set_fields() allows you to adjust the extra field information about the designated user. Its functionality is identical to set_passwd(), but the name is a little more appropriate. This method requires a user name and a hash reference containing new field values.

When setting field values, the old and new values are merged. To delete a previous field value, you must explicitly set it to undef in the hash reference. Otherwise the previous value will be retained.

Arguments:

-user      Name of the user to update
-fields    Hash ref to the fields to update
-name      Alias for -user
-gcos      Alias for -fields

A true result code indicates that the database was successfully updated. The database must be writable for this method to succeed.

set_group()
$resultcode = $db->set_group(-user=>'username',
                             -group=>\@list_of_groups);

This method allows you to set the list of groups that a user belongs to without changing any other information about him or her. It expects a user name and a list reference pointing to the groups to assign the user to. The user will be removed from any groups he previously participated in.

Arguments:

-user      Name of the user to update
-group     List of groups to assign user to
-name      Alias for -user
-grp       Alias for -group

A true result code indicates that the database was successfully updated. The database must be writable for this method to succeed.

delete_user()
$resultcode = $db->delete_user(-user=>'username');

Delete the user and all his associated information from the database. If there are any empty groups after this deletion, they are removed as well. This operation is irreversible.

Arguments:

-user      Name of the user to remove
-name      Alias for -user

A true result code indicates that the database was successfully updated. The database must be writable for this method to succeed.

You may also call this method with a single positional argument:

$resultcode = $db->delete_user('username');
delete_group()
$resultcode = $db->delete_group(-group=>'groupname');

Delete the group from the database. Users who participate in the deleted group are not deleted. However, they may find themselves orphaned (not participating in any groups).

Arguments:

-group      Name of the user to remove
-grp        Alias for -group

A true result code indicates that the database was successfully updated. The database must be writable for this method to succeed.

You may also call this method with a single positional argument:

$resultcode = $db->delete_group('groupname');
errstr()
$error = $db->errstr();

This method returns a string describing the last error encountered by RealmManager.pm. It is not reset by successful function calls, so its contents are only valid after a method returns a false result code.

SEE ALSO

CGI::Builder::Auth::Realm(3) CGI::Builder::Auth::UserAdmin(3) CGI::Builder::Auth::GroupAdmin(3), CGI::Builder::Auth::Authen(3)

AUTHOR

Lincoln Stein <lstein@cshl.org>

Copyright (c) 1997, Lincoln D. Stein

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.