NAME

Contentment::Security::Manager - Interface implemented by Contentment security managers

DESCRIPTION

The security manager is a singleton object used by the Contentment::Security class to determine the security permissions to grant the current request. This module, Contentment::Security::Manager, both documents the interface and provides a very simple implementation. This implementation will be used if no other is provided.

INTERFACE

The security manager interface must implement the following method:

$secman = Contentment::Security::Manager->instance

Return an instance of the security manager. This is named instance because it is generally assumed that this object will be a single (see Class::Singleton). It doesn't really have to be a singleton, but this method will still only be called once.

$principal = $secman->get_principal

Return the Contentment::Security::Principal to associate with the request.

$principal = $secman->lookup_principal($username)

Return a Contentment::Security::Principal matching the given username, $username, or return undef if no match can be found.

If you create a security manager, you need to modify the value of "security_manager" in the "Contentment::Plugin::Security" settings.

IMPLEMENTATION

The built-in security system is simple. It uses Contentment::Security::Profile::Persistent to store usernames with passwords for authenticated users. It uses Contentment::Security::Profile::Scratch to store the rest. It will create a generic principal if no authentication has taken place (i.e., no principal has already been recorded in the Contentment::Session).

Authentication may be performed using the login method. The logout method will return the session to an anonymous principal.

Any authenticated principal will always have at least two roles: "everybody" and "authenticated". Any anonymous principal will always have only two roles: "everybody" and "anonymous".

$test = $secman->login($username, $password)

On success, this method will return a true value and get_principal may be used to fetch the newly authenticated principal. On failure, this value returns false and get_principal will continue to return whatever value was there before.

$secman->logout

This method replaces the principal currently stored in the session with an anonymous principal.

HOOK HANDLERS

Contentment::Security::Manager::begin

This hook handler is for the "Contentment::Session::begin" hook. The handler loads the current principal.

Contentment::Security::Manager::end

This hook handler is for the "Contentment::Session::end" hook. The handler saves the current principal.

FORM HANDLER

Contentment::Security::Manager::process_login_form

On success, this logs the user in.

It expects the following query parameters:

username

This is the username of the user that is logging in.

password

This is the password of the user that is logging in.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

Contentment is licensed and distributed under the same terms as perl itself.