NAME

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

SYNOPSIS

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";
}

DESCRIPTION

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.

METHODS

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.

AUTHORS

Daniel Berrange <dan@berrange.com>

COPYRIGHT

Copyright (C) 2004-2006 Daniel Berrange

SEE ALSO

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