Skip to content

Commit a7567e8

Browse files
arhimedearhimede
authored
Merge pull request #25 from dotkernel/auth-docs
Issue #23: Added authentication and authorization documentations
2 parents bad7e22 + db5dcfa commit a7567e8

3 files changed

Lines changed: 197 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 API identities are delivered to the application from the client through the `Authorization` request
7+
If it is present, the application tries to find and assign the identity to the application. If it is not presented,
8+
DotKernel API assigns a default `guest` identity, represented by an instance of the class
9+
`Mezzio\Authentication\UserInterface`.
10+
11+
## Configuration
12+
13+
Authentication in DotKernel API is built 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 stored in
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 info.
19+
20+
## How it works
21+
22+
DotKernels 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 populated with the data needed for authentication.
31+
32+
In DotKernel API, authenticated users come from either the `admin` or 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 guessed 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+
Token generation in DotKernel API 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` = column `name` from the `oauth_clients` table
52+
- `client_secret` = column `secret` from the `oauth_clients` table
53+
- `scope` = column `scope` from the `oauth_scopes` table
54+
- `username` = column `identity` from table `admin`/`user`
55+
- `password` = column `password` from table `admin`/`user`
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+
```json
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 API provides the ability to refresh the access token, by generating a new one using the expired access token's `refresh_token`.
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+
```json
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: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
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 APIs implementation of authorization uses `Mezzio\Authorization\Rbac\LaminasRbac` as a model of
7+
Role-Based Access Control (RBAC).
8+
9+
## How it works
10+
11+
In DotKernel API each authenticatable entity (admin/user) comes with their roles table where you can define
12+
roles for each entity. RBAC comes in to ensure that each entity has the appropriate role and permission to access a resource.
13+
14+
The authorization happens through the `Api\App\Middleware\AuthorizationMiddleware` middleware.
15+
16+
## Configuration
17+
18+
DotKernel API makes use of `mezzio-authorization-rbac` and upon installation all the configuration is already made
19+
in order for the authorization to work.
20+
21+
The configuration file for the role and permission definitions is `config/autoload/authorization.global.php`.
22+
23+
```php
24+
'mezzio-authorization-rbac' => [
25+
'roles' => [
26+
AdminRole::ROLE_SUPERUSER => [],
27+
AdminRole::ROLE_ADMIN => [
28+
AdminRole::ROLE_SUPERUSER,
29+
],
30+
UserRole::ROLE_GUEST => [
31+
UserRole::ROLE_USER,
32+
],
33+
],
34+
'permissions' => [
35+
AdminRole::ROLE_SUPERUSER => [],
36+
AdminRole::ROLE_ADMIN => [
37+
'other.routes'
38+
'admin.list',
39+
'home'
40+
],
41+
UserRole::ROLE_USER => [
42+
'other.routes',
43+
'user.my-account.update',
44+
'user.my-account.view',
45+
],
46+
UserRole::ROLE_GUEST => [
47+
'other.routes',
48+
'security.refresh-token',
49+
'error.report',
50+
'home',
51+
],
52+
],
53+
],
54+
```
55+
56+
> See [mezzio-authorization-rbac](https://docs.mezzio.dev/mezzio-authorization-rbac/v1/basic-usage/)
57+
for more information.
58+
59+
## Usage
60+
61+
Based on the configuration file above, we have 2 admins roles (`superuser`, `admin`) and 2 users roles (`user`, `guest`).
62+
63+
Roles inherit the permissions from their parents:
64+
65+
- `superuser` has no parent
66+
- `admin` has `superuser` as a parent which means `superuser` will inherit `admin` permissions
67+
- `user` has no parent
68+
- `guest` has `user` as a parent which means `user` will inherit `guest` permissions
69+
70+
For each role we defined an array of permissions. A permission in DotKernel API is basically a route name.
71+
72+
As you can see, the `superuser` does not have it's own permissions, because it inherits all the permissions from `admin`,
73+
no need to define permissions for it unless necessary.
74+
75+
The `user` role, inherits all the permission from `guest` so no need to define that `user` can access `home` route, but
76+
`guest` cannot access user-specific routes.

‎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)