Merge pull request #5 from ezimuel/feature/doc

Added intro, authentication adapter and user repository docs

Author: weierophinney

docs/book/auth-adapter.md

@@ -0,0 +1,49 @@
+# Authentication adapters
+
+The authentication adapters for `zend-expressive-authentication` implement the
+interface `Zend\Expressive\Authentication\AuthenticationInterface` reported
+below:
+
+```php
+namespace Zend\Expressive\Authentication;
+
+use Psr\Http\Message\ServerRequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+interface AuthenticationInterface
+{
+    /**
+     * Authenticate the PSR-7 request and return a valid user
+     * or null if not authenticated
+     *
+     * @param ServerRequestInterface $request
+     * @return UserInterface|null
+     */
+    public function authenticate(ServerRequestInterface $request): ?UserInterface;
+
+    /**
+     * Generate the unauthorized response
+     *
+     * @param ServerRequestInterface $request
+     * @return ResponseInterface
+     */
+    public function unauthorizedResponse(ServerRequestInterface $request): ResponseInterface;
+}
+```
+
+This interface contains two functions: `authenticate()` to check if a PSR-7
+request contains a valid credential and `unauthorizedResponse()` to return the
+unauthorized response.
+
+We provided 4 authentication adapters:
+
+- [zend-expressive-authentication-basic](https://github.com/zendframework/zend-expressive-authentication-basic),
+  for [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
+  supporting only `bcrypt` as password hashing algorithm (for security reason);
+- [zend-expressive-authentication-session](https://github.com/zendframework/zend-expressive-authentication-session),
+  for authenticate username and password credentials using PHP session;
+- [zend-expressive-authentication-zendauthentication](https://github.com/zendframework/zend-expressive-authentication-zendauthentication),
+  supporting the [zend-authentication](https://github.com/zendframework/zend-authentication)
+  component;
+- [zend-expressive-authentication-oauth2](https://github.com/zendframework/zend-expressive-authentication-oauth2),
+  supporting [OAuth2](https://oauth.net/2/) authentication framework.

docs/book/intro.md

@@ -1,4 +1,94 @@
-# zendframework/zend-expressive-authentication
+# Zend Expressive Authentication
 
-This component provides authentication abstraction and authentication middleware
-for PSR-7 applications.
+This component provides authentication abstraction using a middleware approach
+for [PSR-7](http://www.php-fig.org/psr/psr-7/) applications.
+
+The authentication is provided using the [AuthenticationMiddleware](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/AuthenticationMiddleware.php)
+class. This middleware consumes an [AuthenticationInterface](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/AuthenticationInterface.php)
+adapter to check if a [PSR-7](http://www.php-fig.org/psr/psr-7/) request is
+authenticated or not. If authenticated, the middleware executes the next
+delegate in the pipeline, passing a [UserInterface](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/UserInterface.php)
+object as attribute in the request. If the request is not authenticated, the
+middleware returns a `401 Unauthorized` response.
+
+The `Zend\Expressive\Authentication\UserInterface` is defined as follows:
+
+```php
+namespace Zend\Expressive\Authentication;
+
+interface UserInterface
+{
+    /**
+     * Get the username
+     *
+     * @return string
+     */
+    public function getUsername(): string;
+
+    /**
+     * Get all user roles
+     *
+     * @return string[]
+     */
+    public function getUserRoles() : array;
+}
+```
+
+The `UserInterface` attribute in the PSR-7 request can be used for checking
+if a user has been authenticated or not, e.g. it can be used to verify the
+authorization level of a user (for this scope, it is used by [zend-expressive-authotization](https://github.com/zendframework/zend-expressive-authorization)).
+
+## Usage in the route
+
+The `AuthenticationMiddleware` can be used to authenticate a route. You just
+need to add the class name of the middleware in the pipeline of a route.
+As an example:
+
+```php
+$app->get('/admin/dashboard', [
+    Zend\Expressive\Authentication\AuthenticationMiddleware::class,
+    Admin\Action\Dashboard::class
+], 'admin.dashboard');
+```
+
+In this example, the `AuthenticationMiddleware` is executed as first middleware
+of the route `admin.dashboard`. If the user is authenticated, the application
+executes the `Dashboard` action, otherwise it returns a `401 Unauthorized`
+response.
+
+## Choosing an authentication adapter
+
+You can choose an authentication adapter and a user repository through the
+service container configuration.
+You need to specify the service for authentication using the name `Zend\Expressive\Authentication\AuthenticationInterface` and the user registry
+using the service name `Zend\Expressive\Authentication\UserRepositoryInterface::class`.
+
+For instance, using `zend-servicemanager` you can easily configure these two
+services using `aliases`. Below, it's reported an example of configuration using
+the *HTTP Basic Access Authentication* adapter and the *htpasswd* file as user
+repository.
+
+```php
+// ConfigProvider.php
+
+use Zend\Expressive\Authentication\AuthenticationInterface;
+use Zend\Expressive\Authentication\UserRepositoryInterface;
+
+class ConfigProvider
+{
+    // ...
+
+    public function getDependencies() : array
+    {
+        return [
+            'aliases' => [
+                AuthenticationInterface::class => Basic\BasicAccess::class,
+                UserRepositoryInterface::class => UserRepository\Htpasswd::class
+            ],
+            // ...
+        ];
+    }
+
+    // ...
+}
+```

docs/book/user-repository.md

@@ -0,0 +1,38 @@
+# User Repository
+
+An authentication adapter can take the information about the users from
+different repository: a [htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html)
+file, a database, a custom repository, etc. We provided an interface, the
+`Zend\Expressive\Authentication\UserRepositoryInterface`, to access the user
+storage. This interface is reported below:
+
+```php
+namespace Zend\Expressive\Authentication;
+
+interface UserRepositoryInterface
+{
+    /**
+     * Authenticate the credential (username) using a password
+     * or using only the credential string (e.g. token based credential)
+     * It returns the authenticated user or null.
+     *
+     * @param string $credential can be also a token
+     */
+    public function authenticate(string $credential, string $password = null) : ?UserInterface;
+
+    /**
+     * Get the user roles if present.
+     *
+     * @param string $username
+     * @return string[]
+     */
+    public function getRolesFromUser(string $username) : array;
+}
+```
+It contains two functions: `authenticate()` and `getRolesFromUser()`. The first
+is used to authenticate using the user's credential. If authenticated, the
+result will be a UserInterface instance, otherwise a null value is returned.
+
+The second function is `getRolesFromUser()` and it specify how to retrieve
+the roles of a user. If a user does not have roles, this function will return
+an empty array.

mkdocs.yml

@@ -3,6 +3,8 @@ site_dir: docs/html
 pages:
     - index.md
     - Introduction: intro.md
+    - 'Authentication adapter': auth-adapter.md
+    - 'User repository': user-repository.md
 site_name: Authentication middleware
 site_description: 'Authentication middleware for Expressive and PSR-7 applications'
 repo_url: 'https://github.com/zendframework/zend-expressive-authentication'