Merge branch 'hotfix/5'

Close #5

Author: weierophinney

docs/book/intro.md

@@ -0,0 +1,51 @@
+# Authentication adapters
+
+The authentication adapters for `zend-expressive-authentication` implement the
+interface `Zend\Expressive\Authentication\AuthenticationInterface`:
+
+```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 method: `authenticate()` to check if a PSR-7
+request contains a valid credential, and `unauthorizedResponse()` to generate
+and return an unauthorized response.
+
+We provide 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 the password hashing algorithm to ensure best
+  security.
+- [zend-expressive-authentication-session](https://github.com/zendframework/zend-expressive-authentication-session),
+  for authenticating username/password credential pairs and persisting them
+  between requests via PHP sessions.
+- [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 the [OAuth2](https://oauth.net/2/) authentication framework via the
+  [league/oauth2-server](https://oauth2.thephpleague.com/) package.

docs/book/v1/auth-adapter.md

@@ -0,0 +1,100 @@
+# Zend Expressive Authentication
+
+This component provides authentication abstraction using a middleware approach
+for [PSR-7](http://www.php-fig.org/psr/psr-7/) and
+[PSR-15](https://github.com/php-fig/fig-standards/tree/4b417c91b89fbedaf3283620ce432b6f51c80cc0/proposed/http-handlers)
+applications.
+
+Authentication is performed 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
+middleware in the application, passing a [UserInterface](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/UserInterface.php)
+object via a request attribute. If the request is not authenticated, the
+middleware returns a `401 Unauthorized` response based on the authentication
+adapter provided.
+
+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 consumed 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 is an example of configuration using the *HTTP
+Basic Access Authentication* adapter and the *htpasswd* file as the 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/v1/intro.md

@@ -0,0 +1,44 @@
+# User Repository
+
+An authentication adapter can pull user information from a variety
+of repositories:
+
+- an [htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html) file
+- a database
+- a cache
+
+zend-expressive-authentication provides an interface,
+`Zend\Expressive\Authentication\UserRepositoryInterface`, to access this user
+storage:
+
+```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 specifies how to retrieve
+the roles for a user. If a user does not have roles, this function will return
+an empty array.

docs/book/v1/user-repository.md

@@ -2,8 +2,11 @@ docs_dir: docs/book
 site_dir: docs/html
 pages:
     - index.md
-    - Introduction: intro.md
+    - Introduction: v1/intro.md
+    - Reference:
+      - 'Authentication adapter': v1/auth-adapter.md
+      - 'User repository': v1/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'
-copyright: 'Copyright (c) 2017 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'
+copyright: 'Copyright (c) 2018 <a href="http://www.zend.com/">Zend Technologies USA Inc.</a>'