You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/book/v7/core-features/authentication.md
+94-21Lines changed: 94 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,11 +6,18 @@ It ensures that the entity making the request has the proper credentials to acce
6
6
**Dotkernel API** identities are delivered to the application from the client through the `Authorization` request.
7
7
If it is present, the application tries to find and assign the identity to the application.
8
8
If it is not presented, Dotkernel API assigns a default `guest` identity, represented by an instance of the class `Mezzio\Authentication\UserInterface`.
9
+
Guests can access public endpoints but cannot access protected resources (those requiring user or admin roles).
10
+
Check out the [Authorization page](https://docs.dotkernel.org/api-documentation/v7/core-features/authentication/) for more details on role-based access.
9
11
10
12
## Configuration
11
13
14
+
Dotkernel API uses the **OAuth2 password grant flow** for authentication.
15
+
This allows users to exchange their credentials (username/password) for access tokens.
16
+
These tokens are then used for later requests instead of repeatedly sending credentials.
17
+
12
18
Authentication in Dotkernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already configured out of the box.
13
-
But if you want to dig more, the configuration is stored in `config/autoload/local.php` under the `authentication` key.
19
+
To customize authentication behavior (token lifetimes, algorithms, etc.), edit `config/autoload/local.php` under the `authentication` key.
20
+
See the [Mezzio OAuth2 documentation](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration) for all available options.
@@ -23,32 +30,46 @@ It allows each user of your application to generate API tokens for their account
23
30
24
31
The authentication happens through the middleware in the `Api\App\Middleware\AuthenticationMiddleware`.
25
32
26
-
## Database
33
+
###Database
27
34
28
-
When you install **Dotkernel API** for the first time, you need to run the migrations and seeders.
35
+
When you install **Dotkernel API** for the first time, you need to run the migrations and seeders (fixtures).
29
36
All the tables required for authentication are automatically created and populated.
30
37
31
-
In Dotkernel API, authenticated users come from either the `admin` or the `user` table.
32
-
We choose to keep the admin table separated from the users to prevent users of the application from accessing sensitive data, which only the administrators of the application should access.
38
+
```shell
39
+
php ./vendor/bin/doctrine-migrations migrate
40
+
php ./bin/doctrine fixtures:execute
41
+
```
42
+
43
+
The commands above create OAuth tables (oauth_clients, oauth_scopes, oauth_*) and seed the initial credentials:
The `oauth_clients` table is pre-populated with the default `admin` and `frontend` clients with the same password as their names (**we recommend you change the default passwords**).
48
+
Check out the [Installation Guide](https://docs.dotkernel.org/api-documentation/v7/installation/doctrine-orm/) for more details.
35
49
36
-
As you guessed each client serves to authenticate `admin` or `user`.
50
+
In Dotkernel API, authenticated users come from either the `admin` or the `user` tables.
51
+
We chose to keep the admin and user tables separate to prevent users of the application from accessing sensitive data that only administrators should access.
37
52
38
53
Another table that is pre-populated is the `oauth_scopes` table, with the `api` scope.
39
54
40
55
### Issuing API Tokens
41
56
42
57
Token generation in Dotkernel API is done using the `password``grant_type` scenario, which in this case allows authentication to an API using the user's credentials (generally a username and password).
43
58
44
-
The client sends a POST request to the `/security/generate-token` with the following parameters:
59
+
The `POST /security/generate-token` endpoint accepts OAuth2 credentials and returns both an access token (for making API calls) and a refresh token (for refreshing expired access tokens).
60
+
61
+
The client requires the following parameters:
45
62
46
-
-`grant_type` = password.
47
-
-`client_id` = column `name` from the `oauth_clients` table
48
-
-`client_secret` = column `secret` from the `oauth_clients` table
49
-
-`scope` = column `scope` from the `oauth_scopes` table
50
-
-`username` = column `identity` from table `admin`/`user`
51
-
-`password` = column `password` from table `admin`/`user`
> Composer is required to install Dotkernel `api`.
9
+
> You can install Composer from the [official site](https://getcomposer.org/).
10
+
11
+
> Before you begin, make sure that you have navigated your command prompt to the folder where you copied the files in the previous step.
12
+
13
+
## Install Dependencies Using Composer
8
14
9
15
Run this command in the command prompt.
10
16
11
17
> Use the **CLI** to ensure interactivity for proper configuration.
18
+
> In some IDEs, Composer may not be able to prompt for configuration settings.
12
19
13
20
```shell
14
21
composer install
15
22
```
16
23
24
+
The automatic setup script performs these tasks:
25
+
26
+
- Installs the packages listed in the `composer.json` file and their dependencies into the `vendor` folder.
27
+
- Creates the `composer.lock` file that locks all dependencies to exact versions (you can still run `composer update` to replace them with newer versions, if available and installable without conflicts).
28
+
- Configures PHP CodeSniffer, a utility to detect code style errors in PHP code.
29
+
- Generate and save the OAuth2 keys in the `data/oauth` folder.
30
+
- Performed by this script `./bin/generate-oauth2-keys.php`.
31
+
- Creates the initial `config/autoload` configuration files.
32
+
- Performed by this script `./bin/composer-post-install-script.php`.
33
+
- These files are created:
34
+
- config/autoload/local.php
35
+
- config/autoload/local.test.php
36
+
- config/autoload/mail.global.php
37
+
38
+
> The post install commands are run automatically on every `composer install` and `composer update`.
39
+
> The scripts check if the files exist to prevent overwriting them.
40
+
17
41
You should see this text below, along with a long list of packages to be installed instead of the `[...]`.
18
-
In this example there are 164 packages, though the number can change in future updates.
19
-
You will find the packages in the `vendor` folder.
42
+
43
+
> In this example there are 146 packages, though the number can change in future updates.
20
44
21
45
```shell
22
46
No composer.lock file present. Updating dependencies to latest instead of installing from lock file. See https://getcomposer.org/install for more information.
23
47
Loading composer repositories with package information
0 commit comments