Authen::PAAS::Context - authentication a subject using login modules

  use Authen::PAAS::Context;
  use Authen::PAAS::SimpleCallback;
  use Config::Record;

  my $config = Config::Record->new("/etc/myapp.cfg");

  my $context = Authen::PAAS::Context->new($config, "myapp");

  my $callbacks = {
    "username" => Authen::PAAS::SimpleCallback->new("joeblogs"),
    "password" => Authen::PAAS::SimpleCallback->new("123456"),
  };

  my $subject = $context->login($callbacks);

  unless ($subject) {
     die "could not authenticate subject"
  }

  .. do some work using the subject ..

  $context->logout($subject);

The Authen::PAAS::Context module provides the controller for invoking a number of login modules, and having them populate a subject with principals and credentials. The authentication process consists of two stages. In the first phase the login method is invoked on all modules to perform the actual authentication process. If a module's authentication process succeded, then it may wish to store state to represent the result of authentication in the supplied instance of Authen::PAAS::State. If the first phase was successful overall, then the commit method will be invoked on all modules. The module's commit method will check the stored state for the result of the first phase, and if it was successful, then it will add one or more principals and zero or more credentials to the subject. If there is a terminal failure of the authentication process at any point, the abort() method will be invoked on all modules

The Config::Record module is used for accessing configuration file information. The configuration file defines the set of login modules used for performing authentication. The modules have associated flags controlling operation of the login process upon success/failure of a module. The configuration is stored in a single list, named auth.$APP where $APP is the name token passed into the constructor of the Authen::PAAS::Context object. Each element in the list is a dictionary, with the key module defining the class name of the login module, the key flags defining the login flags and options defining any module specific options. For example, a web application may have a a username/password in the main login page, but elsewhere use a cookie as the authentication data. In this case, a configuration look like

  auth.mail-archive = (
    {
      module = Authen::PAAS::DB::PasswdLogin
      flags = optional
    }
    {
      module = Authen::PAAS::CGI::CookieLogin
      flags = requisite
      options = {
	secret = /etc/authen-paas/authen-paas-cgi-secret.dat
	user-module = Authen::PAAS::DB::User
      }
    }
  )

$obj = Authen::PAAS::Context->new();

Create

my $subject = $ctx->login(\%callbacks);

Attempt to authenticate the user, using data obtained from the callbacks passed in as the first parameter. The callbacks should be a hash reference, where keys are the callback name, and the values are instances of the Authen::PAAS::Callback module. If authentication succeeded, an instance of the Authen::PAAS::Subject module will be returned, otherwise an undefined value will be returned.

$ctx->logout($subject)

Takes an authenticated subject and performs a logout operation. This method would typically destroy any tokens / credentials that might exist beyond the lifetime of the current process.

Daniel Berrange <dan@berrange.com>

Copyright (C) 2004-2006 Daniel Berrange

Authen::PAAS, Authen::PAAS::LoginModule, Authen::PAAS::Subject