/ 
Apache-iNcom-0.09
River stage zero No dependents
/ DBIx::UserDB

NAME

DBIx::UserDB - Module to manage a user database using DBIx::SearchProfiles

SYNOPSIS

    use DBIx::UserDB;
    use DBIx::SearchProfiles;

    my $db     = new DBIx::SearchProfiles( ... );
    my $userdb = new DBIx::UserDB( $db );

    my $user   = { username => $username, password => $password };
    $user      = $userdb->user_create( $user );

    # Later on
    my $user   = $userdb->login( $user, $password );
    die "Login failed" unless $user;

    # Much later
    if ( $userdb->allowed( $user, $target, "DELETE" ) ) {
	...
    }

DESCRIPTION

The DBIx::UserDB uses DBIx::SearchProfiles to manage a user and group database and may be also used to manage complex ACL. The user and group schema may be modified for application specific data since only a few fields are required by the UserDB. This is possible thanks to DBIx::SearchProfiles.

CONCEPTS

Users and Groups

Users are represented as hash and as one SQL table. They have a unique username and a unique uid. Group have also a unique name and a unique gid. A user may be a members of many groups.

ACLs

UserDB can also be used to manage complex ACL (Acccess Control Lists). Access to resources is determined by the tuple (user,target,privilege) which determines if a user has the required privilege on target. Privilege and target are treated as application specific character strings.

CONFIGURATION

In order to use DBIx::UserDB you will need to create a few tables in your DMBS and to create the approriate DBIx::SearchProfiles.

Here is the minimal schema required in your DBMS :

    CREATE TABLE userdb (
	uid	    SERIAL PRIMARY KEY,
	username    CHAR(32) UNIQUE,
	password    CHAR(32)
    );

    CREATE TABLE groupdb (
	gid	    SERIAL PRIMARY KEY,
	groupname   CHAR(32) UNIQUE
    );

    CREATE TABLE groupmembers (
	gid	    INT REFERENCES groupdb,
	uid	    INT REFERENCES userdb,
	PRIMARY KEY (gid,uid)
    );

    CREATE TABLE user_acl (
	uid	    INT REFERENCES userdb,
	target	    CHAR(128),
	privilege   CHAR(32),
	negated	    BOOL DEFAULT 0,
	PRIMARY KEY (uid,target,privilege)
    );

    CREATE TABLE group_acl (
	gid	    INT REFERENCES groupdb,
	target	    CHAR(128),
	privilege   CHAR(32),
	negated	    BOOL DEFAULT 0,
	PRIMARY KEY (gid,target,privilege)
    );

    CREATE TABLE default_acl (
	target	    CHAR(128),
	privilege   CHAR(32),
	negated	    BOOL DEFAULT 0,
	PRIMARY KEY (target,privilege)
    );

This SQL was tested with PostgreSQL, modify according to your RDBMS. And here is its related DBIx::SearchProfiles profile :

    {
    userdb	 =>
      {
       fields	 => [qw( username password ) ],
       keys	 => [qw( uid )],
       table	 => "userdb",
      },
    groupdb	 =>
      {
       query	 => q{ SELECT m.gid,uid,groupname FROM groupdb, groupmembers m
		       WHERE  uid = ? },
       params	 => [ qw( uid ) ],
       fields	 => [ qw( groupname ) ],
       keys	 => [ qw( gid )],
       table	 => "groupdb",
      }	,
    }

You may add any fields to the groupdb and userdb tables as long as you add them to the profiles. The userdb profile should be a record profile (see DBIx::SearchProfiles(3)) and groupdb should contains both template profile's information (for finding the users associated with a group) and record profile's information (for inserting and updating group's information). Additionaly you may change the fields length of all required fields.

Passwords are uuencoded for storage (for minimal privacy not for security), so take this into account when setting the password field's length. If you want to store password in plaintext, use the scramble_password method.

INITIALIZATION

Initializing the DBIx::UserDB is as simple as

my $userdb = new DBIx::UserDB( $DB, "userdb", "groupdb" );

The first parameter is a DBIx::SearchProfiles object which will be used to access the database. The second parameter is the name of the profile that should be used to access the users' information (defaults to "userdb"). The third parameter is the name of the profile to use for group access (defaults to "groupdb").

scramble_password ( [new_setting] )

Return the scramble password setting. You may also change the setting by giving the method a new value. If scramble password is true, user's password will be uuencoded before being stored in the database.

USER METHODS

Here are the methods for managing users in the database.

user_create ( \%user )

This method creates a user with the information specified in the hash reference in the database. In the user's hash, at least the fields username and password should be set.

The methods return true on success and false if there is already a username with that name in the database. Exception are thrown on database errors. Additionally, on return, the method will add the UID of the newly created user.

user_search ( \%params )

This method will return users matching the DBIx::SearchProfiles query specification in a reference to an array.

user_get ( $uid_or_name )

This method takes a UID or username and return the corresponding user (as an hash reference) or undef if there is no such user.

The key groups in the user's hash contains the names of the groups of which this user is a member.

user_login ( $username, $password )

This method will return the user which have the corresponding username and password or undef if the username or password is invalid.

user_delete ( \%user )

This method removes the given user from the database.

user_update ( \%user )

This method updates database information of the given user. This method has no effects on the group information. Use the group_add_user and group_remove_user methods for modifying the groups associated with a user.

GROUP METHODS

Here are the methods to manage group information

group_create ( \%group )

This method creates a new group in the database. At least the groupname key should be set in the hash.

This methods returns false if there is already a group with the same groupname. It returns true if the creation succeeded. Additionnaly, on return, the key gid will be set in the original group's hash.

group_search ( \%params )

This method will search the database for groups matching the DBIx::SearchProfiles record search and will return its results as a reference to an hash.

group_get ( $gid_or_name )

This method takes a gid or groupname and will fetch the corresponding group. It returns the corresponding group or undef if there is no such group. Additionnaly there is a key members defined in the resulting hash which contains in an array the name of all members of the group.

group_delete ( \%group )

This methods removes the given group from the database.

group_update ( \%group )

This methods updates the information associated with the given group in that database. This methods doesn't modify the list of members of this group. User group_add_user and group_remove_user for that.

group_add_user ( \%group, \%user )

Adds the user to that group.

group_remove_user ( \%group, \%user )

Removes the user from that group.

ACL METHODS

Here are the methods to access the ACL information :

grant ( \%user_or_group, $target, $privilege )

Grant the specified privilege on target to that group or user. If you want to set the default policy regarding that target and privilege, use undef as the user parameter.

deny ( \%user_or_group, $target, $privilege )

Deny the specific privilege on target to that group or user. Use undef if you want the default policy to be deny.

revoke ( \%user_or_group, $target, $privilege )

Removes the specified privilege on target associated with user or group. If you want to remove the default policy, use undef as the user parameter.

NOTE: Revoking is not the same as denying. Revoking removes the entry from the ACL which means that the resulting policy will be determined by other entry in the ACL (i.e: group or default). When using deny, you are explicitely determining the level of access.

allowed ( \%user, $target, $privilege )

Determine if user has prilivege on target. This how the access is determined :

  1. Determine if there is an entry (user,target,privilege). If an entry is found, true or false will be returned depending whether that privilege was granted or denied.

  2. Check for an entry (group,target,privilege) for each group of which the user is a member. For the group policy to apply, all group must share the same result.

    For example, if user A is member of group A and B and group A is granted the requested privilege and group B is denied, the group policy doesn't apply to that particular user. Schematically :

    Group A Granted + Group B Granted = User Granted
Group A Granted + Group B Denied  = Default policy will apply
Group A Denied  + Group B Denied  = User Denied

  3. A entry (target,privilege) will be lookup in the default policy. If one is found, that policy will apply.

  4. Access is denied.

BUGS AND LIMITATIONS

Please report bugs, suggestions, patches and thanks to <bugs@iNsu.COM>.

Authentication is limited to clear text password authentication.

User and group data structure is restricted to single level hash.

AUTHOR

Copyright (c) 1999 Francis J. Lacoste and iNsu Innovations Inc. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms as perl itself.

SEE ALSO

DBIx::SearchProfiles(3) Apache::UserDBAuthen(3) Apache::UserDBAuthz(3)