Skip to content

Commit b931651

Browse files
claurospaceclaurospace
committed
added authentication and authorization documentations
1 parent bad7e22 commit b931651

3 files changed

Lines changed: 198 additions & 0 deletions

File tree

‎docs/book/v4/core-features/authentication.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Authentication
2+
3+
Authentication is the process by which an identity is presented to the application. It ensures that the entity
4+
making the request has the proper credentials to access the API.
5+
6+
DotKernel's API identities are delivered to the application from the client through the `Authorization` request
7+
header.  If it is present, the application tries to find and assign the identity to the application. If it is not presented,
8+
DotKernel's API assigns a default `guest` identity, represented by an instance of the class
9+
`Mezzio\Authentication\UserInterface`.
10+
11+
## Configuration
12+
13+
DotKernel's API authentication is made around `mezzio/mezzio-authentication-oauth2` component and is already configured.
14+
with what is necessary in order to work. But if you want to dig more, the configuration is hold on.
15+
`config/autoload/local.php` under the authentication key.
16+
17+
> You can check the [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration)
18+
> configuration part for more digging.
19+
20+
## How it works
21+
22+
DotKernel's API authentication system can be used for SPAs (single-page applications), mobile applications, and
23+
simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts.
24+
25+
The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`.
26+
27+
## Database
28+
29+
When DotKernel API is installed for the first time, and you run the migrations and seeders, all the tables
30+
needed for authentication are automatically created and inserted with the data needed for authentication.
31+
32+
In DotKernel's API, authentication users can be from the `admin` table and from the `users` table. We choose to keep the admin
33+
table separated from the users to prevent users of the application from accessing sensitive data, which only the administrators
34+
of the application should access.
35+
36+
Knowing this, upon migrations, the `oauth_clients` table is pre-populated with the default `admin` and `frontend` clients with
37+
the same password as their names. (you can change those passwords.).
38+
39+
As you guested each client serves to authenticate `admin` or `users`.
40+
41+
Another table that is pre-populated is the `oauth_scopes` table, with the `api` scope.
42+
43+
### Issuing API Tokens
44+
45+
In DotKernel's API, generating tokens is done using the `password` `grand_type` scenario, which in this case allows authentication
46+
to an API using the user's credentials (generally a username and password).
47+
48+
The client sends a POST request to the `/security/generate-token` with the following parameters:
49+
50+
- `grant_type` = password.
51+
- `client_id` with the client name (from `oauth_clients` table).
52+
- `client_secret` with the client secret (password from `oauth_clients` table for the client).
53+
- `scope` with the scope from `oauth_scopes` table.
54+
- `username` with the user’s username.
55+
- `password` with the user’s password.
56+
57+
```shell
58+
POST /security/generate-token HTTP/1.1
59+
Accept: application/json
60+
Content-Type: application/json
61+
{
62+
"grant_type": "password",
63+
"client_id": "frontend",
64+
"client_secret": "frontend",
65+
"scope": "api",
66+
"username": "test@dotkernel.com",
67+
"password": "dotkernel"
68+
}
69+
```
70+
71+
The server responds with a JSON as follows:
72+
73+
```php
74+
{
75+
"token_type": "Bearer",
76+
"expires_in": 86400,
77+
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
78+
"refresh_token": "def5020087199939a49d0f2f818..."
79+
}
80+
```
81+
82+
Next time when you make a request to the server to an authenticated endpoint, the client should use
83+
the `Authorization` header request.
84+
85+
```shell
86+
GET /users/1 HTTP/1.1
87+
Accept: application/json
88+
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
89+
```
90+
91+
### Refreshing tokens
92+
93+
DotKernel's API provides the ability to refresh the access token, generating a new one.
94+
95+
The clients need to send a `POST` request to the `/security/refresh-token` with the following request
96+
97+
```shell
98+
POST /security/refresh-token HTTP/1.1
99+
Accept: application/json
100+
Content-Type: application/json
101+
{
102+
"grant_type": "refresh_token",
103+
"client_id": "frontend",
104+
"client_secret": "frontend",
105+
"scope": "api",
106+
"refresh_token" : "def5020087199939a49d0f2f818..."
107+
}
108+
```
109+
110+
The server responds with a JSON as follows:
111+
112+
```php
113+
{
114+
"token_type": "Bearer",
115+
"expires_in": 86400,
116+
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
117+
"refresh_token": "def5020087199939a49d0f2f818..."
118+
}
119+
```

‎docs/book/v4/core-features/authorization.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Authorization
2+
3+
Authorization is the process by which a system take a validated identity and checks if that identity has access to a
4+
given resource.
5+
6+
DotKernel's APIs implementation of the authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of
7+
Role-Based Access Control (RBAC)
8+
9+
## How it works
10+
In DotKernel's API each authenticatable entity (admin and users) comes in with their roles table where you can define
11+
roles for each entity. RBAC comes in to ensure that each entity has the appropriate role and permission to access a resource.
12+
13+
The authorization happens through the middleware in the `Api\App\Middleware\AuthorizationMiddleware`.
14+
15+
## Configuration
16+
17+
In DotKernel API make use of `mezzio-authorization-rbac` and upon installation all the configuration is already made
18+
in order for the authorization to work.
19+
20+
The configuration where you define roles and permission is hold on `config/autoload/authorization.global.php`
21+
22+
```php
23+
'mezzio-authorization-rbac' => [
24+
'roles' => [
25+
AdminRole::ROLE_SUPERUSER => [],
26+
AdminRole::ROLE_ADMIN => [
27+
AdminRole::ROLE_SUPERUSER,
28+
],
29+
UserRole::ROLE_GUEST => [
30+
UserRole::ROLE_USER,
31+
],
32+
],
33+
'permissions' => [
34+
AdminRole::ROLE_SUPERUSER => [],
35+
AdminRole::ROLE_ADMIN => [
36+
'other.routes'
37+
'admin.list',
38+
'home'
39+
],
40+
UserRole::ROLE_USER => [
41+
'other.routes',
42+
'user.my-account.update',
43+
'user.my-account.view',
44+
],
45+
UserRole::ROLE_GUEST => [
46+
'other.routes',
47+
'security.refresh-token',
48+
'error.report',
49+
'home',
50+
],
51+
],
52+
],
53+
```
54+
55+
> You can check [mezzio-authorization-rbac](https://docs.mezzio.dev/mezzio-authorization-rbac/v1/basic-usage/) for more
56+
> in depth
57+
58+
## Usage
59+
60+
Based on the configuration file above, we have 2 admins roles (`superuser`, `admin`) and 2 users roles (`user`, `guest`).
61+
62+
A role can inherit the roles of their parent:
63+
64+
- `superuser` has no parent
65+
- `admin` has `superuser` as a parent which means `superuser` will inherit `admin` permissions
66+
67+
68+
- `user` has no parent
69+
- `guest` has `user` as a parent which means `user` will inherit `guest` permissions
70+
71+
For each role we defined an array of permissions. A permission in DotKernel's is basically a route name.
72+
73+
As you can see, the `superuser` does not have any permission, because inherit all the permission from `admin`no
74+
need to define permission for him again.
75+
76+
The `user` role, inherit all the permission from `guest` so no need to define that `user` can access `home` route, but
77+
`guest` cannot access `user.my-account.view` route.

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ nav:
2626
- "Library Flow for Email": v4/flow/library-flow-for-email.md
2727
- Core Features:
2828
- "Content Validation": v4/core-features/content-validation.md
29+
- "Authentication": v4/core-features/authentication.md
30+
- "Authorization": v4/core-features/authorization.md
2931
- "Exceptions": v4/core-features/exceptions.md
3032
- Tutorials:
3133
- "Creating a book module": v4/tutorials/create-book-module.md

0 commit comments

Comments
 (0)