Merge pull request #13 from activecollab/feature/auth-events

Add authentication events.

Author: ilijastuden

README.md

@@ -8,7 +8,9 @@ Table of Contents:
   * [Accessing Users](#accessing-users)
 * [Authorizers](#authorizers)
   * [Request Aware Auhtorizers](#request-aware-auhtorizers)
+  * [Exception Aware Authorizers](#exception-aware-auhtorizers)
 * [Transports](#transports)
+* [Events](#events)
 * [Authentication Middlewares](#authentication-middlewares)
 * [Working with Passwords](#working-with-passwords)
   * [Hashing and Validating Passwords](#hashing-and-validating-passwords)
@@ -255,6 +257,37 @@ if (!$transport->isApplied()) {
 }
 ```
 
+## Events
+
+Authentication utility throws events for which you can write handlers. Here's an example:
+
+```php
+<?php
+
+namespace MyApp;
+
+use ActiveCollab\Authentication\Authentication;
+
+$auth = new Authentication([]);
+$auth->onUserAuthorizationFailed(function(array $credentials) {
+    // Log attempt for user's username.
+});
+$auth->onUserAuthorizationFailed(function(array $credentials) {
+    // If third attempt, notify administrator that particular user has trouble logging in.
+});
+$auth->onUserAuthorizationFailed(function(array $credentials) {
+    // If fifth attempt, block IP address for a couple of minutes, to cool it down.
+});
+```
+
+As you can see from the example above, you can provide multiple handlers for the same event. Following events are available:
+
+1. `onUserAuthenticated` - (visit) User is recognized by its session cookie, token etc, so it was authenticated. Arguments provided to the callaback are user instance [AuthenticatedUserInterface], and authentication result [AuthenticationResultInterface].
+1. `onUserAuthorized` (login) User provided valid credentials, and system authorized it. Arguments provided to the callaback are user instance [AuthenticatedUserInterface], and authentication result [AuthenticationResultInterface].
+1. `onUserAuthorizationFailed` (login failed)  User tried to authorize, but provided credentials were not valid, or authorization failed due to other reasons (SSO service down, etc). Arguments provided to the callback are user's credentials [array], as well as the failure reason ([Exception] or [Throwable]).
+1. `onUserSet` - User is set - authenticated, authorizer, or app set the user using its own logic. Argument provided to the callback is the user instance [AuthenticatedUserInterface].
+1. `setOnUserDeauthenticated` (logout) User logged out. Argument provided to the callback is authentication method that got terminated [AuthenticationResultInterface].
+
 ## Authentication Middlewares
 
 `AuthenticationInterface` interface assumes that implementation will be such that it can be invoked as a middleware in a [PSR-7](http://www.php-fig.org/psr/psr-7/) middleware stack. That is why implementation of `__invoke` method in middleware stack fashion is part of the interface.
@@ -446,5 +479,5 @@ Login policy implements `\JsonSerializable` interface, and can be safely encoded
 
 ## To Do
 
-1. Consider adding previously used passwords repository, so library can enforce no-repeat policy for passwords,
-1. Add `onAuthentication()`, `onAuthorization()`, `onDeauthentication()` events to `AuthenticationInterface`.
+1. Consider adding previously used passwords repository, so library can enforce no-repeat policy for passwords.
+1. Remove deprecated `AuthenticationInterface::setOnAuthenciatedUserChanged()`.

src/Authentication.php

@@ -18,6 +18,7 @@
 use ActiveCollab\Authentication\Authorizer\AuthorizerInterface;
 use ActiveCollab\Authentication\Exception\InvalidAuthenticationRequestException;
 use Exception;
+use InvalidArgumentException;
 use LogicException;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
@@ -45,9 +46,29 @@ class Authentication implements AuthenticationInterface
     private $authenticated_with;
 
     /**
-     * @var callable|null
+     * @var callable[]
      */
-    private $on_authencated_user_changed;
+    private $on_user_authenticated = [];
+
+    /**
+     * @var callable[]
+     */
+    private $on_user_authorized = [];
+
+    /**
+     * @var callable[]
+     */
+    private $on_user_authorization_failed = [];
+
+    /**
+     * @var callable[]
+     */
+    private $on_user_set = [];
+
+    /**
+     * @var callable[]
+     */
+    private $on_user_deauthenticated = [];
 
     /**
      * @param array $adapters
@@ -74,6 +95,8 @@ public function __invoke(ServerRequestInterface $request, ResponseInterface $res
             if ($auth_result instanceof AuthenticationTransportInterface) {
                 $this->setAuthenticatedUser($auth_result->getAuthenticatedUser());
                 $this->setAuthenticatedWith($auth_result->getAuthenticatedWith());
+
+                $this->triggerEvent('user_authenticated', $auth_result->getAuthenticatedUser(), $auth_result->getAuthenticatedWith());
             }
 
             list($request, $response) = $auth_result->applyTo($request, $response);
@@ -91,18 +114,30 @@ public function __invoke(ServerRequestInterface $request, ResponseInterface $res
      */
     public function authorize(AuthorizerInterface $authorizer, AdapterInterface $adapter, array $credentials, $payload = null)
     {
-        $user = $authorizer->verifyCredentials($credentials);
-        $authenticated_with = $adapter->authenticate($user, $credentials);
+        try {
+            $user = $authorizer->verifyCredentials($credentials);
+            $authenticated_with = $adapter->authenticate($user, $credentials);
+
+            $this->triggerEvent('user_authorized', $user, $authenticated_with);
 
-        return new AuthorizationTransport($adapter, $user, $authenticated_with, $payload);
+            return new AuthorizationTransport($adapter, $user, $authenticated_with, $payload);
+        } catch (Exception $e) {
+            $this->triggerEvent('user_authorization_failed', $credentials, $e);
+
+            throw $e;
+        }
     }
 
     /**
      * {@inheritdoc}
      */
     public function terminate(AdapterInterface $adapter, AuthenticationResultInterface $authenticated_with)
     {
-        return $adapter->terminate($authenticated_with);
+        $termination_result = $adapter->terminate($authenticated_with);
+
+        $this->triggerEvent('user_deauthenticated', $authenticated_with);
+
+        return $termination_result;
     }
 
     /**
@@ -166,9 +201,7 @@ public function &setAuthenticatedUser(AuthenticatedUserInterface $user = null)
     {
         $this->authenticated_user = $user;
 
-        if (is_callable($this->on_authencated_user_changed)) {
-            call_user_func($this->on_authencated_user_changed, $user);
-        }
+        $this->triggerEvent('user_set', $user);
 
         return $this;
     }
@@ -191,13 +224,77 @@ public function &setAuthenticatedWith(AuthenticationResultInterface $value)
         return $this;
     }
 
+    /**
+     * Trigger an internal event.
+     *
+     * @param  string $event_name
+     * @param  array  $arguments
+     * @return $this
+     */
+    private function &triggerEvent($event_name, ...$arguments)
+    {
+        $property_name = "on_{$event_name}";
+
+        /** @var callable $handler */
+        foreach ($this->$property_name as $handler) {
+            call_user_func_array($handler, $arguments);
+        }
+
+        return $this;
+    }
+
     /**
      * {@inheritdoc}
      */
-    public function &setOnAuthenciatedUserChanged(callable $value = null)
+    public function &onUserAuthenticated(callable $value)
     {
-        $this->on_authencated_user_changed = $value;
+        $this->on_user_authenticated[] = $value;
 
         return $this;
     }
+
+    public function &onUserAuthorized(callable $value)
+    {
+        $this->on_user_authorized[] = $value;
+
+        return $this;
+    }
+
+    public function &onUserAuthorizationFailed(callable $value)
+    {
+        $this->on_user_authorization_failed[] = $value;
+
+        return $this;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function &onUserSet(callable $value)
+    {
+        $this->on_user_set[] = $value;
+
+        return $this;
+    }
+
+    public function &setOnUserDeauthenticated(callable $value)
+    {
+        $this->on_user_deauthenticated[] = $value;
+
+        return $this;
+    }
+
+    /**
+     * Kept for backward compatibility reasons. Will be removed.
+     *
+     * {@inheritdoc}
+     */
+    public function &setOnAuthenciatedUserChanged(callable $value = null)
+    {
+        if (empty($value)) {
+            throw new InvalidArgumentException('Value needs to be a callable.');
+        }
+
+        return $this->onUserSet($value);
+    }
 }

src/AuthenticationInterface.php

@@ -83,8 +83,41 @@ public function getAuthenticatedWith();
     public function &setAuthenticatedWith(AuthenticationResultInterface $value);
 
     /**
+     * @param  callable $value
+     * @return $this
+     */
+    public function &onUserAuthenticated(callable $value);
+
+    /**
+     * @param  callable $value
+     * @return $this
+     */
+    public function &onUserAuthorized(callable $value);
+
+    /**
+     * @param  callable $value
+     * @return $this
+     */
+    public function &onUserAuthorizationFailed(callable $value);
+
+    /**
+     * @param  callable $value
+     * @return $this
+     */
+    public function &onUserSet(callable $value);
+
+    /**
+     * @param  callable $value
+     * @return $this
+     */
+    public function &setOnUserDeauthenticated(callable $value);
+
+    /**
+     * Use onUserSet() instead.
+     *
      * @param  callable|null $value
      * @return $this
+     * @deprecated
      */
     public function &setOnAuthenciatedUserChanged(callable $value = null);
 }

test/src/AuthenticationMiddlewareTest.php

@@ -206,21 +206,4 @@ public function testExceptionOnMultipleIds()
 
         call_user_func(new Authentication([$this->browser_session_adapter, $this->token_bearer_adapter]), $request, $response);
     }
-
-    public function testOnAuthenticatedUserCallback()
-    {
-        /** @var ServerRequestInterface $request */
-        $request = $this->request->withHeader('Authorization', 'Bearer awesome-token');
-
-        $middleware = new Authentication([$this->token_bearer_adapter]);
-
-        $callback_is_called = false;
-        $middleware->setOnAuthenciatedUserChanged(function () use (&$callback_is_called) {
-            $callback_is_called = true;
-        });
-
-        call_user_func($middleware, $request, $this->response);
-
-        $this->assertTrue($callback_is_called);
-    }
 }