Authen::PAAS::Subject - represents an authenticated party

  use Authen::PAAS::Subject;

  ####### Creating a populating a subject..

  # Create a new anonymous subject with no credentials
  my $subject = Authen::PAAS::Subject->new();

  # Add a principal eg a UNIX username, or a Kerberos
  # principal, or some such
  my $prin = SomePrincipal->new();
  $subject->add_principal($prin)

  # Add a credential. eg some form of magic token
  # representing a previously added principal
  my $cred = SomeCredential->new($principal)
  $subject->add_credential($cred);




  ######## Fetching and querying a subject

  # Create a context module for performing auth
  my $context = Context->new($config, "myapp");

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

  if ($subject) {
      # Retrieve set of all principals
      my @princs = $subject->principals;

      # Or only get principal of particular class
      my $princ = $subject->principal("SomePrincipal");

      # Retrieve set of all credentials
      my @cred = $subject->credentials;

      # Or only get credential of particular class
      my $cred = $subject->credential("SomeCredential");
  } else {
      die "login failed";
  }

The Authen::PAAS::Subject module provides a representation of an authenticated party, be they a human user, or a independantly operating computing service. An authenticated subject will have one of more principals associated with them, which can be thought of as their set of names. These are represented by the Authen::PAAS::Principal module. Some authentication mechanisms will also associate some form of security related token with a subject, thus an authenticated subject may also have zero or more credentials. These are represented by the Authen::PAAS::Credential module.

An authenticated subject is typically obtained via the login method on the Authen::PAAS::Context module. This creates an anonymous subject, and invokes a set of login modules (Authen::PAAS::LoginModule), which in turn populate the subject with principals and credentials.

my $subject = Authen::PAAS::Subject->new();

Create a new subject, with no initial principals or credentials.

$subject->add_principal($owner, $principal)

Adds a principal to the subject. The $owner parameter should be the class name of the login module owning the principal. The principal parameter must be a subclass of the Authen::PAAS::Principal class.

$subject->remove_principal($owner[, $type]);

Removes a previously added principal from the subject. The $id parameter is the index of the principal previously added via the add_principal method.

my @principals = $subject->principals_by_owner($owner);

Retrieves a list of all the principals for the subject associated with the owner specified in the $owner parameter. The value of the $owner parameter is the class name of a login module

my @principals = $subject->principals_by_type($type);

Retrieves the first matching principal of a given type. The $type parameter should be the Perl module name of the principal implementation.

my @principals = $subject->principals;

Retrieves a list of all the principals for the subject.

$subject->add_credential($owner, $credential)

Adds a credential to the subject. The $owner parameter should be the class name of the login module owning the credential. The credential parameter must be a subclass of the Authen::PAAS::Credential class.

$subject->remove_credential($owner[, $type]);

Removes a previously added credential from the subject. The $id parameter is the index of the credential previously added via the add_credential method.

my @credentials = $subject->credentials_by_owner($owner);

Retrieves a list of all the credentials for the subject associated with the owner specified in the $owner parameter. The value of the $owner parameter is the class name of a login module

my @credentials = $subject->credentials_by_type($type);

Retrieves the first matching credential of a given type. The $type parameter should be the Perl module name of the credential implementation.

my @credentials = $subject->credentials;

Retrieves a list of all the credentials for the subject.

Daniel Berrange <dan@berrange.com>

Copyright (C) 2004-2006 Daniel Berrange

Authen::PAAS::Context, Authen::PAAS::Credential, Authen::PAAS::Principal