Skip to content

Commit 61dff5d

Browse files
arhimedearhimede
committed
typos and validations
1 parent 5a8d0c7 commit 61dff5d

File tree

5 files changed

+203
-198
lines changed

5 files changed

+203
-198
lines changed

‎LICENSE

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2023 DotKernel
3+
Copyright (c) 2024 DotKernel
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

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

Lines changed: 121 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,121 @@
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": "[email protected]",
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-
```
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
14+
configured 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
18+
> [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration)
19+
> configuration part for more info.
20+
21+
## How it works
22+
23+
DotKernels API authentication system can be used for SPAs (single-page applications), mobile applications, and
24+
simple, token-based APIs. It allows each user of your application to generate API tokens for their accounts.
25+
26+
The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`.
27+
28+
## Database
29+
30+
When **DotKernel API** is installed for the first time, and you run the migrations and seeders, all the tables
31+
needed for authentication are automatically created and populated with the data needed for authentication.
32+
33+
In DotKernel API, authenticated users come from either the `admin` or the `users` table. We choose to keep the admin
34+
table separated from the users to prevent users of the application from accessing sensitive data, which only the
35+
administrators of the application should access.
36+
37+
Knowing this, upon migrations, the `oauth_clients` table is pre-populated with the default `admin` and `frontend`
38+
clients with the same password as their names (you can change those passwords).
39+
40+
As you guessed each client serves to authenticate `admin` or `users`.
41+
42+
Another table that is pre-populated is the `oauth_scopes` table, with the `api` scope.
43+
44+
### Issuing API Tokens
45+
46+
Token generation in DotKernel API is done using the `password` `grand_type` scenario, which in this case allows
47+
authentication to an API using the user's credentials (generally a username and password).
48+
49+
The client sends a POST request to the `/security/generate-token` with the following parameters:
50+
51+
- `grant_type` = password.
52+
- `client_id` = column `name` from the `oauth_clients` table
53+
- `client_secret` = column `secret` from the `oauth_clients` table
54+
- `scope` = column `scope` from the `oauth_scopes` table
55+
- `username` = column `identity` from table `admin`/`user`
56+
- `password` = column `password` from table `admin`/`user`
57+
58+
```shell
59+
POST /security/generate-token HTTP/1.1
60+
Accept: application/json
61+
Content-Type: application/json
62+
{
63+
"grant_type": "password",
64+
"client_id": "frontend",
65+
"client_secret": "frontend",
66+
"scope": "api",
67+
"username": "[email protected]",
68+
"password": "dotkernel"
69+
}
70+
```
71+
72+
The server responds with a JSON as follows:
73+
74+
```json
75+
{
76+
"token_type": "Bearer",
77+
"expires_in": 86400,
78+
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
79+
"refresh_token": "def5020087199939a49d0f2f818..."
80+
}
81+
```
82+
83+
Next time when you make a request to the server to an authenticated endpoint, the client should use
84+
the `Authorization` header request.
85+
86+
```shell
87+
GET /users/1 HTTP/1.1
88+
Accept: application/json
89+
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
90+
```
91+
92+
### Refreshing tokens
93+
94+
DotKernel API provides the ability to refresh the access token, by generating a new one using the expired access
95+
token's `refresh_token`.
96+
97+
The clients need to send a `POST` request to the `/security/refresh-token` with the following request
98+
99+
```shell
100+
POST /security/refresh-token HTTP/1.1
101+
Accept: application/json
102+
Content-Type: application/json
103+
{
104+
"grant_type": "refresh_token",
105+
"client_id": "frontend",
106+
"client_secret": "frontend",
107+
"scope": "api",
108+
"refresh_token" : "def5020087199939a49d0f2f818..."
109+
}
110+
```
111+
112+
The server responds with a JSON as follows:
113+
114+
```json
115+
{
116+
"token_type": "Bearer",
117+
"expires_in": 86400,
118+
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
119+
"refresh_token": "def5020087199939a49d0f2f818..."
120+
}
121+
```

0 commit comments

Comments
 (0)