Skip to content

Commit 23b7f26

Browse files
weierophinneyweierophinney
committed
Edits authorization documentation
Edits the documentation for both technical details, as well as content and flow.
1 parent 23eb6f5 commit 23b7f26

File tree

3 files changed

+86
-67
lines changed

3 files changed

+86
-67
lines changed

‎README.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,15 @@
33
[![Build Status](https://secure.travis-ci.org/zendframework/zend-expressive-authorization.svg?branch=master)](https://secure.travis-ci.org/zendframework/zend-expressive-authorization)
44
[![Coverage Status](https://coveralls.io/repos/github/zendframework/zend-expressive-authorization/badge.svg?branch=master)](https://coveralls.io/github/zendframework/zend-expressive-authorization?branch=master)
55

6-
Zend-expressive-authorization is a middleware for [Expressive](https://github.com/zendframework/zend-expressive)
7-
and [PSR-7](http://www.php-fig.org/psr/psr-7/) applications for authorize
6+
Zend-expressive-authorization provides middleware for [Expressive](https://github.com/zendframework/zend-expressive)
7+
and [PSR-7](http://www.php-fig.org/psr/psr-7/) applications for authorizing
88
specific routes based on [ACL](https://en.wikipedia.org/wiki/Access_control_list)
99
or [RBAC](https://en.wikipedia.org/wiki/Role-based_access_control) systems.
1010

1111
## Installation
1212

13-
You can install the *zend-expressive-authorization* library with composer:
13+
You can install the zend-expressive-authorization library with
14+
[Composer](https://getcomposer.org):
1415

1516
```bash
1617
$ composer require zendframework/zend-expressive-authorization

‎docs/book/v1/auth-adapter.md‎

Lines changed: 54 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,63 @@
11
# Authorization adapters
22

3-
You can choose an authorization adapter through the service container
4-
configuration.
5-
6-
You need to specify the service for authentication using the name
7-
`Zend\Expressive\Authorization\AuthorizationInterface`.
8-
9-
For instance, using [zend-servicemanager](https://github.com/zendframework/zend-servicemanager)
10-
you can easily configure the authorization using aliases. Below is an example of
11-
configuration using an ACL or RBAC adapter.
12-
13-
14-
```
15-
use Zend\Expressive\Authorization\AuthorizationInterface;
16-
use Zend\Expressive\Authorization\Acl\ZendAcl;
17-
use Zend\Expressive\Authorization\Rbac\ZendRbac;
18-
19-
return [
20-
// ...
21-
'dependencies' => [
22-
// ...
23-
'aliases' => [
24-
// ...
25-
AuthorizationInterface::class => ZendAcl::class,
26-
// or AuthorizationInterface::class => ZendRbac::class
27-
]
28-
]
29-
];
30-
```
31-
32-
The RBAC adapter is managed by [zend-expressive-authorization-rbac](https://github.com/zendframework/zend-expressive-authorization-rbac)
33-
and ACL is managed by [zend-expressive-authorization-acl](https://github.com/zendframework/zend-expressive-authorization-acl/)
34-
library.
35-
36-
If you want to use one of these adapters, you need to install via composer:
3+
You can configure the authorization adapter to use via your service container
4+
configuration. Specifically, you can either map the service name
5+
`Zend\Expressive\Authorization\AuthorizationInterface` to a factory, or alias it
6+
to the appropriate service.
7+
8+
For instance, using [Expressive container configuration](https://docs.zendframework.com/zend-expressive/v3/features/container/config/),
9+
you could select the zend-expressive-authorization-acl adapter in either of the
10+
following ways:
11+
12+
- Using an alias:
13+
```php
14+
use Zend\Expressive\Authorization\AuthorizationInterface;
15+
use Zend\Expressive\Authorization\Acl\ZendAcl;
16+
17+
return [
18+
'dependencies' => [
19+
// Using an alias:
20+
'aliases' => [
21+
AuthorizationInterface::class => ZendAcl::class,
22+
],
23+
],
24+
];
25+
```
26+
27+
- Mapping to a factory:
28+
```php
29+
use Zend\Expressive\Authorization\AuthorizationInterface;
30+
use Zend\Expressive\Authorization\Acl\ZendAclFactory;
31+
32+
return [
33+
'dependencies' => [
34+
// Using an alias:
35+
'factories' => [
36+
AuthorizationInterface::class => ZendAclFactory::class,
37+
],
38+
],
39+
];
40+
```
41+
42+
We provide two different adapters.
43+
44+
- The RBAC adapter is provided by [zend-expressive-authorization-rbac](https://github.com/zendframework/zend-expressive-authorization-rbac).
45+
- The ACL adapter is provided by [zend-expressive-authorization-acl](https://github.com/zendframework/zend-expressive-authorization-acl/).
46+
47+
Each adapter is installable via [Composer](https://getcomposer.org):
3748

3849
```bash
39-
composer require zendframework/zend-expressive-authorization-rbac
50+
$ composer require zendframework/zend-expressive-authorization-rbac
4051
# or
41-
composer require zendframework/zend-expressive-authorization-acl
52+
$ composer require zendframework/zend-expressive-authorization-acl
4253
```
4354

44-
In both these adapters, we used the **route name** as resource. This means, you
45-
can specify if a role is authorized to access a specific HTTP route or not.
46-
This is just a general idea for implementing an authorization system. You can
47-
create your own system implementing the [AuthorizationInterface](https://github.com/zendframework/zend-expressive-authorization/blob/master/src/AuthorizationInterface.php),
48-
as reported above.
55+
In each adapter, we use the **route name** as the resource. This means you
56+
can specify if a role is authorized to access a specific HTTP _route_.
57+
However, this is just one approach to implementing an authorization system; you
58+
can create your own system by implementing the
59+
[AuthorizationInterface](https://github.com/zendframework/zend-expressive-authorization/blob/master/src/AuthorizationInterface.php).
4960

50-
For more information about these adapters please read the [RBAC documentation](https://docs.zendframework.com/zend-expressive-authorization-rbac/)
61+
For more information on the adapters, please read the
62+
[RBAC documentation](https://docs.zendframework.com/zend-expressive-authorization-rbac/)
5163
and the [ACL documentation](https://docs.zendframework.com/zend-expressive-authorization-acl/).

‎docs/book/v1/intro.md‎

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,20 @@
11
# Zend Expressive Authorization
22

3-
This component provides authorization abstraction middleware for [PSR-7](https://www.php-fig.org/psr/psr-7/)
4-
applications.
3+
This component provides authorization middleware for [PSR-7](https://www.php-fig.org/psr/psr-7/)
4+
and [PSR-15](https://www.php-fig.org/psr/psr-15/) applications.
55

6-
An authorization system needs authentication first. To verify that an identity
7-
has access to something (i.e. is authorized) we need to have an identity,
8-
if authenticated.
6+
An authorization system first needs authentication: to verify that an identity
7+
has access to something (i.e., is authorized) we first need the _identity_, which
8+
is provided during authentication.
99

10-
You can easily implement an authentication system using [zend-expressive-authentication](https://github.com/zendframework/zend-expressive-authentication)
11-
library. This library provides an `AuthenticationMiddleware` class that verify
12-
credentials using the HTTP request and store an identity as [PSR-7 attribute](https://docs.zendframework.com/zend-expressive/v2/cookbook/passing-data-between-middleware/).
10+
Authentication is provided via the package
11+
[zend-expressive-authentication](https://docs.zendframework.com/zend-expressive-authentication/).
12+
That library provides an `AuthenticationMiddleware` class that verify
13+
credentials using the HTTP request, and stores the identity via a [PSR-7 request attribute](https://docs.zendframework.com/zend-expressive/v2/cookbook/passing-data-between-middleware/).
1314

14-
The identity attribute generated by [zend-expressive-authentication](https://github.com/zendframework/zend-expressive-authentication)
15-
is named `Zend\Expressive\Authentication\UserInterface` and it contains a
16-
`UserInterface` object.
15+
The identity generated by zend-expressive-authentication is stored as the
16+
request attribute `Zend\Expressive\Authentication\UserInterface` as a
17+
`UserInterface` implementation. That interface looks like the following:
1718

1819
```php
1920
namespace Zend\Expressive\Authentication;
@@ -24,34 +25,39 @@ interface UserInterface
2425
* Get the unique user identity (id, username, email address or ...)
2526
*/
2627
public function getIdentity() : string;
28+
2729
/**
2830
* Get all user roles
2931
*
3032
* @return Iterable
3133
*/
3234
public function getRoles() : iterable;
35+
3336
/**
3437
* Get a detail $name if present, $default otherwise
3538
*/
3639
public function getDetail(string $name, $default = null);
40+
3741
/**
3842
* Get all the details, if any
3943
*/
4044
public function getDetails() : array;
4145
}
4246
```
4347

44-
**Zend Expressive Authorization** consumes this identity attribute.
45-
It checks if a user's role (of the `UserInterface` object) is authorized
46-
(granted) to execute the HTTP request.
48+
zend-expressive-authorization consumes this identity attribute. It checks if a
49+
user's role (as retrieved from the `UserInterface` object) is authorized
50+
(granted) to the perform the current HTTP request.
51+
52+
Authorization is performed using the `isGranted()` method of the
53+
[AuthorizationInterface](https://github.com/zendframework/zend-expressive-authorization/blob/master/src/AuthorizationInterface.php).
4754

48-
The authorization is performed using the `isGranted()` function of the [AuthorizationInterface](https://github.com/zendframework/zend-expressive-authorization/blob/master/src/AuthorizationInterface.php).
55+
We offer two adapters:
4956

50-
We offer two adapters: [zend-expressive-authorization-rbac](https://github.com/zendframework/zend-expressive-authorization-rbac)
51-
for implementing a Role-Based Access Control ([RBAC](https://en.wikipedia.org/wiki/Role-based_access_control))
52-
and [zend-expressive-authorization-acl](https://github.com/zendframework/zend-expressive-authorization-acl/)
53-
for implementing an Access Control List ([ACL](https://en.wikipedia.org/wiki/Access_control_list)).
57+
- [zend-expressive-authorization-rbac](https://github.com/zendframework/zend-expressive-authorization-rbac),
58+
which implements Role-Based Access Controls ([RBAC](https://en.wikipedia.org/wiki/Role-based_access_control))
59+
- [zend-expressive-authorization-acl](https://github.com/zendframework/zend-expressive-authorization-acl/),
60+
which implements an Access Control List ([ACL](https://en.wikipedia.org/wiki/Access_control_list)).
5461

55-
> If you want to know more about authentication using middleware in PHP
56-
> we suggest to read [Authorize users using Middleware](https://framework.zend.com/blog/2017-05-04-authorization-middleware.html)
57-
> blog post.
62+
> If you want to know more about authentication using middleware in PHP,
63+
> we suggest reading the blog post ["Authorize users using Middleware"](https://framework.zend.com/blog/2017-05-04-authorization-middleware.html).

0 commit comments

Comments
 (0)