NAME

POE::Component::UserBase - a component to manage user authentication

SYNOPSIS

  use POE qw(Component::UserBase);

  # The UserBase can deal with many types of repositories.
  # The first kind is a simple file.
  POE::Component::UserBase->spawn
    ( Alias    => 'userbase', # defaults to 'userbase'.
      Protocol => 'file',     # The repository type.
      Cipher   => 'md5',      # defaults to 'crypt'.

      File     => '/home/jgoff/passwd',   # The path to the repository
      Dir      => '/home/jgoff/.persist', # Directory to store persistent
                                          # information.
    );

  POE::Component::UserBase->spawn
    ( Alias         => 'userbase',   # defaults to 'userbase'.
      Protocol      => 'dbi',        # The repository type.
      Cipher        => 'sha1',       # defaults to 'crypt'.

      DBHandle      => $dbh,         # Required, connected to a handle.
      Table         => 'auth',
      UserColumn    => 'user_name',  # defaults to 'username'.
      PassColumn    => 'password',   # defaults to 'password'.
      PersistColumn => 'persistent', # defaults to 'data'. This is our
                                     # persistent data storage.
    );

  # PoCo::UserBase provides generic user-management services to multiple
  # sessions.

  $kernel->post
    ( user_base => log_on => user_name  => $user_name,
                             domain     => $domain,       # optional
		             password   => $password,     # optional
		             persistent => $persistent_reference,
		             response   => $authorized_state,
    );

  $kernel->post
    ( user_base => log_off => user_name => $user_name,
                              password  => $password,    # optional
    );

  $kernel->post
    ( user_base => create => user_name => $user_name,
                             domain    => $domain,       # optional
		             password  => $password,     # optional
    );

  $kernel->post
    ( user_base => delete => user_name => $user_name,
                             domain    => $domain,       # optional
                             password  => $password,     # optional
    );

  $kernel->post
    ( user_base => update => user_name     => $user_name,
	                     domain        => $domain,   # optional
                             password      => $password, # optional
                             new_user_name => $new_name, # optional
		             new_domain    => $new_dom,  # optional
		             new_password  => $new_pass, # optional
    );

DESCRIPTION

POE::Component::UserBase handles basic user authentication and management tasks for a POE server. It can authenticate from sources such as a .htaccess file, database, DBM files, and flat files.

PoCo::UserBase communicates with the client through a previously created SocketFactory. After a client is has connected, PoCo::UserBase interrogates the client for its username and password, and returns the connection data from the socket along with the username and password authenticated.

POE::Component::UserBase's spawn method takes a few parameters to describe the depository of user names. I'd recommend that you not use any crucial system files until you assure yourself that it's indeed safe.

The spawn method has several common parameters. These are listed below.

Alias => $session_alias

Alias sets the name by which the session will be known. If no alias is given, the component defaults to "userbase". The alias lets several sessions interact with the user manager without keeping (or even knowing) hard references to them.

Cipher => $cipher_type

Cipher sets the cipher that will be used to encrypt the password entries. If no cipher is given, the component defaults to "crypt". This uses the native crypt() function. Other cipher choices include 'md5', 'sha1', 'md5_hex', 'sha1_hex', 'md5_base64', and 'sha1_base64'. The 'md5' and 'sha1' cipher types are documented in the Digest::MD5 and Digest::SHA1 class. They're simply different output formats of the original hash.

These parameters are unique to the file Protocol type.

File => $filename

File sets the file name that is used to store user data. This parameter is required.

Dir => $path_to_persistent_directory

Dir Sets the directory that is used to hold the persistence information. This directory holds the frozen persistent data, indexed by the user_name.

These parameters are unique to the dbi Protocol type.

Connection => $dbh_connection

Connection stores a handle to a DBI connection. The database must contain a table which will hold the username, password, and persistent data.

PersistentColumn => $persistent_data_column_name

PersistentColumn specifies the column name used to hold the persistent data. If you can't allocate enough space to hold your persistent data in the database, then you can use the DataFile parameter to define a MLDBM file that will be used to hold this persistent data. The MLDBM data file will be keyed by the username.

DataFile => $data_file_name

DataFile specifies the filename of the MLDBM file used to hold the persistent data store. Use of this parameter is incompatible with Data.

DomainColumn => $domain_column_name

DomainColumn specifies the column used to store the domain column. It defaults to domain.

PasswordColumn => $password_column_name

PasswordColumn specifies the column used to store the password column. It defaults to password.

Table => $dbi_table

Table specifies the table name used to store username, password, and maybe the persistent data stored along with each user.

UserColumn => $user_column_name

UserColumn specifies the column used to store the username column. It defaults to username. In the event that you use the DataFile parameter, this column will be kept in sync with the MLDBM file.

Sessions communicate asynchronously with passive UserBase components. They post their requests through several internal states, and receive data through a state that you specify.

Requests are posted to one of the states below:

log_on

log_on is to be called when a client wants to authenticate a user.

  $kernel->post
    ( user_base => log_on => user_name  => $user_name,
                             domain     => $domain,       # optional
		             password   => $password,     # optional
		             persistent => $persistent_reference,
		             response   => $authorized_state,
    );

log_off

log_off is to be called when a client is finished with a user.

$kernel->post
  ( user_base => log_off => user_name => $user_name,
                            password  => $password,    # optional
  );

create

create lets you create a new user.

  $kernel->post
    ( user_base => create => user_name => $user_name,
                             domain    => $domain,       # optional
		             password  => $password,     # optional
    );

delete

delete lets you delete a user.

$kernel->post
  ( user_base => delete => user_name => $user_name,
                           domain    => $domain,       # optional
                           password  => $password,     # optional
  );

update

update lets you update a user.

  $kernel->post
    ( user_base => update => user_name     => $user_name,
	                     domain        => $domain,   # optional
                             password      => $password, # optional
                             new_user_name => $new_name, # optional
		             new_domain    => $new_dom,  # optional
		             new_password  => $new_pass, # optional
    );

For example, authenticating a user is simply a matter of posting a request to the userBase alias (or whatever you named it). It posts responses back to either the 'authorization accepted' or 'authorizaton failed' state. If it successfully authenticates the user, it then fills the alias referenced in the Persistence parameter with the user data it stored in the database when the user logged out.

SEE ALSO

This component is built upon POE. Please see its source code and the documentation for its foundation modules to learn more.

Also see the test programs in the t/ directory, and the samples in the samples/ directory in the POE/Component/UserBase directory.

BUGS

None currently known.

AUTHOR & COPYRIGHTS

POE::Component::UserBase is Copyright 1999-2000 by Jeff Goff. All rights are reserved. POE::Component::UserBase is free software; you may redistribute it and/or modify it under the same terms as Perl itself.