Aura for PHP

Aura.Auth provides authentication functionality and session tracking using various storage adapters. Currently supported are:

• Apache htpasswd files
• SQL tables via the PDO extension
• IMAP/POP/NNTP via the imap extension
• LDAP and Active Directory via the ldap extension
• OAuth via customized adapters

It makes use of ext/password in PHP 5.5+ or uses ircmaxell/password-compat in earlier versions (more here)

Installation

You can either clone the repo https://github.com/auraphp/Aura.Auth and include the autoload.php file or install via composer as below.

composer require "aura/auth:2.0.0-beta2"

Usage

In this example we are looking into authentication via database using PDO. The Aura\Auth\Verifier\PasswordVerifier class help you to make use of different type of hashing algorithms in PHP. You can pass PASSWORD_DEFAULT to make use of ext/password functions or md5, sha256 etc. It is recommended you use of PASSWORD_DEFAULT.

<?php
require_once __DIR__ . '/vendor/autoload.php';

$auth_factory = new \Aura\Auth\AuthFactory($_COOKIE);
$auth = $auth_factory->newInstance();

$pdo = new \PDO(...);
$cols = array(
    'username', // "AS username" is added by the adapter
    'password', // "AS password" is added by the adapter
    'email',
    'fullname',
    'website'
);
$from = 'users';
$where = 'active = 1';

$hash = new \Aura\Auth\Verifier\PasswordVerifier(PASSWORD_DEFAULT);

$pdo_adapter = $auth_factory->newPdoAdapter($pdo, $hash, $cols, $from, $where);

Assuming you have a database table as below:

CREATE TABLE `users` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `username` varchar(255) NOT NULL COMMENT 'Username',
  `email` varchar(255) NOT NULL COMMENT 'Email',
  `password` varchar(255) NOT NULL COMMENT 'Password',
  `fullname` varchar(255) NOT NULL COMMENT 'Full name',
  `website` varchar(255) DEFAULT NULL COMMENT 'Website',
  `active` int(11) NOT NULL COMMENT '0',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

See more complex example using joins in readme

Verifying a Password

The login service will verify and throw exceptions according to the error happened:

$login_service = $auth_factory->newLoginService($pdo_adapter);
try {
    $login_service->login($auth, array(
            'username' => $_POST['username'],
            'password' => $_POST['password'],
        )
    );
    echo "You are now logged into a new session.";
} catch (\Aura\Auth\Exception\UsernameMissing $e) {
    echo "The 'username' field is missing or empty.";
} catch (\Aura\Auth\Exception\PasswordMissing $e) {
    echo "The 'password' field is missing or empty.";
} catch (\Aura\Auth\Exception\UsernameNotFound $e) {
    echo "The username you entered was not found.";
} catch (\Aura\Auth\Exception\MultipleMatches $e) {
    echo "There is more than one account with that username.";
} catch (\Aura\Auth\Exception\PasswordIncorrect $e) {
    echo "The password you entered was incorrect.";
} catch (\Aura\Auth\Exception\ConnectionFailed $e) {
    echo "Cound not connect to IMAP or LDAP server.";
    echo "This could be because the username or password was wrong,";
    echo "or because the the connect operation itself failed in some way. ";
    echo $e->getMessage();
} catch (\Aura\Auth\Exception\BindFailed $e) {
    echo "Cound not bind to LDAP server.";
    echo "This could be because the username or password was wrong,";
    echo "or because the the bind operations itself failed in some way. ";
    echo $e->getMessage();
}

Maintaining Login State

Resuming a Session

Like PHP, Aura.Auth does not start the session automatically (more info).

If you need to check whether the user is logged in on the next request, you must either start the session via session_start(), or resume the service first before checking the Auth status:

// start session
session_start();

// or use the service to resume any previously-existing session

// $resume_service = $auth_factory->newResumeService($pdo_adapter);
// $resume_service->resume($auth);

echo $auth->getStatus();

Logging Out

The same applies to logout, you should either call session_start or resume service before you try logout, otherwise session data will not be removed:

session_start();
$logout_service = $auth_factory->newLogoutService($pdo_adapter);
$logout_service->logout($auth);

if ($auth->isAnon()) {
    echo "You are now logged out.";
} else {
    echo "Something went wrong; you are still logged in.";
}

Depending upon the adapter methods, you can swap the adapters for convenience. Eg : Aura\Auth\Adapter\PdoAdapter::logout method does nothing, so you can pass a Aura\Auth\Adapter\NullAdapter. But it is not recommended.

Checkout the full example code of the tutorial over https://github.com/harikt/authentication-pdo-example