neutron.auth-manual.md

Neutron/Auth

A pluggable authentication system that can be extended nearly infinitenly, works decently in PHP<5.3, and takes a granular (method-specific) approach to security.

Approach (high level)

As it stands now, the module is centered around enabling calls to a given method to require a series of things to happen before it can run.

This is achieved through code like this:

  public function __construct() {
    parent::__construct();

    $this->setEncryptionKey("test encryption key");

    $this->addValidation('private_access', new Auth_Validators_UsersEither(array(
      'test_user_1', 'test_user_2', 'test_user_3',
    )));
    (... rest of constructor) 

Which tells the system that

• There is an encryption key set, for properly handling passwords and such
• The provided authentication information musts include an user name, and it musts be one of those stated above

And in the proper method, this is enforced via /** * Exposed method that requires some form of authentication * @throws Auth_Exceptions_Unauthorized */ public function private_access() { if ($this->canAccess('private_access')) { //this is will only be visible if there is an user logged in, and also the user satisfies a number of conditions } else { throw new Auth_Exceptions_Unauthorized(METHOD); } }

which checks that not only there is an user logged in, but also that this user is one of those defined in the restrictions above. In this particular case, when this expectations are not satisfied, an exception is thrown. This is good because your system can then handle those in any manner you see fit (like prompting the user for proper credentials).

Approach (in detail)

The idea is that by inheriting from Auth_Controller, you also inherit a complete security system that is run mostly behind your back, and can be relied to exist between requests and such.

In Auth_Controller, there are a number of things going on that you can modify to suit your needs. In the following series of graphics we'll attempt to explain the process in detail.

Now, looking inside canAccess, this is a step-by-step view of what's going on.

The session is asked for the authenticated user, and if there is someone authenticated it all moves to a next stage (if there is no authenticated user, the originating method is inmediately told that access is denied):

![Checks are made on the user] (http://i.imgur.com/gxhymTM.jpg)

In case there is an user in the session, then:

![Additional validations are requested and ran] (http://i.imgur.com/uhqAqqP.jpg)

Aditional validations are requested and ran.

In case everything validated OK, then a positive response is returned, otherwise a negative one.

And that's how the checking is made.

Letting people in

So, at some point you're expected to let someone in, and according to Neutron/Auth, you're expected to do that in a certain manner.