Skip to content
This repository was archived by the owner on Jan 29, 2020. It is now read-only.

Commit 098921a

Browse files
committed
Provides edits for the documentation provided in #5
1 parent ffc6038 commit 098921a

File tree

3 files changed

+44
-30
lines changed

3 files changed

+44
-30
lines changed

docs/book/auth-adapter.md

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
# Authentication adapters
22

33
The authentication adapters for `zend-expressive-authentication` implement the
4-
interface `Zend\Expressive\Authentication\AuthenticationInterface` reported
5-
below:
4+
interface `Zend\Expressive\Authentication\AuthenticationInterface`:
65

76
```php
87
namespace Zend\Expressive\Authentication;
@@ -13,7 +12,7 @@ use Psr\Http\Message\ResponseInterface;
1312
interface AuthenticationInterface
1413
{
1514
/**
16-
* Authenticate the PSR-7 request and return a valid user
15+
* Authenticate the PSR-7 request and return a valid user,
1716
* or null if not authenticated
1817
*
1918
* @param ServerRequestInterface $request
@@ -31,19 +30,22 @@ interface AuthenticationInterface
3130
}
3231
```
3332

34-
This interface contains two functions: `authenticate()` to check if a PSR-7
35-
request contains a valid credential and `unauthorizedResponse()` to return the
36-
unauthorized response.
33+
This interface contains two method: `authenticate()` to check if a PSR-7
34+
request contains a valid credential, and `unauthorizedResponse()` to generate
35+
and return an unauthorized response.
3736

38-
We provided 4 authentication adapters:
37+
We provide 4 authentication adapters:
3938

4039
- [zend-expressive-authentication-basic](https://github.com/zendframework/zend-expressive-authentication-basic),
41-
for [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
42-
supporting only `bcrypt` as password hashing algorithm (for security reason);
40+
for [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication),
41+
supporting only `bcrypt` as the password hashing algorithm to ensure best
42+
security.
4343
- [zend-expressive-authentication-session](https://github.com/zendframework/zend-expressive-authentication-session),
44-
for authenticate username and password credentials using PHP session;
44+
for authenticating username/password credential pairs and persisting them
45+
between requests via PHP sessions.
4546
- [zend-expressive-authentication-zendauthentication](https://github.com/zendframework/zend-expressive-authentication-zendauthentication),
4647
supporting the [zend-authentication](https://github.com/zendframework/zend-authentication)
47-
component;
48+
component.
4849
- [zend-expressive-authentication-oauth2](https://github.com/zendframework/zend-expressive-authentication-oauth2),
49-
supporting [OAuth2](https://oauth.net/2/) authentication framework.
50+
supporting the [OAuth2](https://oauth.net/2/) authentication framework via the
51+
[league/oauth2-server](https://oauth2.thephpleague.com/) package.

docs/book/intro.md

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
# Zend Expressive Authentication
22

33
This component provides authentication abstraction using a middleware approach
4-
for [PSR-7](http://www.php-fig.org/psr/psr-7/) applications.
4+
for [PSR-7](http://www.php-fig.org/psr/psr-7/) and
5+
[PSR-15](https://github.com/php-fig/fig-standards/tree/4b417c91b89fbedaf3283620ce432b6f51c80cc0/proposed/http-handlers)
6+
applications.
57

6-
The authentication is provided using the [AuthenticationMiddleware](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/AuthenticationMiddleware.php)
8+
Authentication is performed using the [AuthenticationMiddleware](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/AuthenticationMiddleware.php)
79
class. This middleware consumes an [AuthenticationInterface](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/AuthenticationInterface.php)
810
adapter to check if a [PSR-7](http://www.php-fig.org/psr/psr-7/) request is
911
authenticated or not. If authenticated, the middleware executes the next
10-
delegate in the pipeline, passing a [UserInterface](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/UserInterface.php)
11-
object as attribute in the request. If the request is not authenticated, the
12-
middleware returns a `401 Unauthorized` response.
12+
middleware in the application, passing a [UserInterface](https://github.com/zendframework/zend-expressive-authentication/blob/master/src/UserInterface.php)
13+
object via a request attribute. If the request is not authenticated, the
14+
middleware returns a `401 Unauthorized` response based on the authentication
15+
adapter provided.
1316

1417
The `Zend\Expressive\Authentication\UserInterface` is defined as follows:
1518

@@ -36,7 +39,8 @@ interface UserInterface
3639

3740
The `UserInterface` attribute in the PSR-7 request can be used for checking
3841
if a user has been authenticated or not, e.g. it can be used to verify the
39-
authorization level of a user (for this scope, it is used by [zend-expressive-authotization](https://github.com/zendframework/zend-expressive-authorization)).
42+
authorization level of a user (for this scope, it is consumed by
43+
[zend-expressive-authotization](https://github.com/zendframework/zend-expressive-authorization)).
4044

4145
## Usage in the route
4246

@@ -53,19 +57,21 @@ $app->get('/admin/dashboard', [
5357

5458
In this example, the `AuthenticationMiddleware` is executed as first middleware
5559
of the route `admin.dashboard`. If the user is authenticated, the application
56-
executes the `Dashboard` action, otherwise it returns a `401 Unauthorized`
60+
executes the `Dashboard` action; otherwise it returns a `401 Unauthorized`
5761
response.
5862

5963
## Choosing an authentication adapter
6064

6165
You can choose an authentication adapter and a user repository through the
6266
service container configuration.
63-
You need to specify the service for authentication using the name `Zend\Expressive\Authentication\AuthenticationInterface` and the user registry
67+
68+
You need to specify the service for authentication using the name
69+
`Zend\Expressive\Authentication\AuthenticationInterface` and the user registry
6470
using the service name `Zend\Expressive\Authentication\UserRepositoryInterface::class`.
6571

6672
For instance, using `zend-servicemanager` you can easily configure these two
67-
services using `aliases`. Below, it's reported an example of configuration using
68-
the *HTTP Basic Access Authentication* adapter and the *htpasswd* file as user
73+
services using `aliases`. Below is an example of configuration using the *HTTP
74+
Basic Access Authentication* adapter and the *htpasswd* file as the user
6975
repository.
7076

7177
```php

docs/book/user-repository.md

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
# User Repository
22

3-
An authentication adapter can take the information about the users from
4-
different repository: a [htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html)
5-
file, a database, a custom repository, etc. We provided an interface, the
6-
`Zend\Expressive\Authentication\UserRepositoryInterface`, to access the user
7-
storage. This interface is reported below:
3+
An authentication adapter can pull user information from a variety
4+
of repositories:
5+
6+
- an [htpasswd](https://httpd.apache.org/docs/current/programs/htpasswd.html) file
7+
- a database
8+
- a cache
9+
10+
zend-expressive-authentication provides an interface,
11+
`Zend\Expressive\Authentication\UserRepositoryInterface`, to access this user
12+
storage:
813

914
```php
1015
namespace Zend\Expressive\Authentication;
@@ -29,10 +34,11 @@ interface UserRepositoryInterface
2934
public function getRolesFromUser(string $username) : array;
3035
}
3136
```
37+
3238
It contains two functions: `authenticate()` and `getRolesFromUser()`. The first
3339
is used to authenticate using the user's credential. If authenticated, the
34-
result will be a UserInterface instance, otherwise a null value is returned.
40+
result will be a `UserInterface` instance, otherwise a null value is returned.
3541

36-
The second function is `getRolesFromUser()` and it specify how to retrieve
37-
the roles of a user. If a user does not have roles, this function will return
42+
The second function is `getRolesFromUser()` and it specifies how to retrieve
43+
the roles for a user. If a user does not have roles, this function will return
3844
an empty array.

0 commit comments

Comments
 (0)