diff --git a/docs/book/v4/core-features/authentication.md b/docs/book/v4/core-features/authentication.md index 47d85411..86eced9b 100644 --- a/docs/book/v4/core-features/authentication.md +++ b/docs/book/v4/core-features/authentication.md @@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api` ### Issuing API Tokens -Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows +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). The client sends a POST request to the `/security/generate-token` with the following parameters: diff --git a/docs/book/v5/core-features/authentication.md b/docs/book/v5/core-features/authentication.md index 47d85411..86eced9b 100644 --- a/docs/book/v5/core-features/authentication.md +++ b/docs/book/v5/core-features/authentication.md @@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api` ### Issuing API Tokens -Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows +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). The client sends a POST request to the `/security/generate-token` with the following parameters: diff --git a/docs/book/v5/openapi/write-documentation.md b/docs/book/v5/openapi/write-documentation.md index cc0da40c..9247ce54 100644 --- a/docs/book/v5/openapi/write-documentation.md +++ b/docs/book/v5/openapi/write-documentation.md @@ -107,4 +107,4 @@ To summarize, the typical scenario on working on your own instance of Dotkernel - create new module (example: `Book`) - add functionality to your new module (routes, entities, repositories, handlers, services, tests etc) - create file `OpenAPI.php` in the new module and describe each new endpoint -- generate latest version of documentation file as described [here](./generate-documentation.md) +- generate latest version of documentation file as described [in this tutorial](./generate-documentation.md) diff --git a/docs/book/v6/core-features/authentication.md b/docs/book/v6/core-features/authentication.md index 47d85411..86eced9b 100644 --- a/docs/book/v6/core-features/authentication.md +++ b/docs/book/v6/core-features/authentication.md @@ -43,7 +43,7 @@ Another table that is pre-populated is the `oauth_scopes` table, with the `api` ### Issuing API Tokens -Token generation in Dotkernel API is done using the `password` `grand_type` scenario, which in this case allows +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). The client sends a POST request to the `/security/generate-token` with the following parameters: diff --git a/docs/book/v6/extended-features/handler-structure.md b/docs/book/v6/extended-features/handler-structure.md index 647819f5..0b4fb7b1 100644 --- a/docs/book/v6/extended-features/handler-structure.md +++ b/docs/book/v6/extended-features/handler-structure.md @@ -5,7 +5,7 @@ The goal of this update is to implement PSR-15 handlers into Dotkernel API. ## What is a handler? -In DotKernel 6.0, a "handler" is the piece of code that reacts when a user makes a specific request (like visiting a webpage or submitting a form). +In Dotkernel 6.0, a "handler" is the piece of code that reacts when a user makes a specific request (like visiting a webpage or submitting a form). It's basically the "controller" that decides what happens next. HTTP request handlers are at the core of any web application. @@ -38,6 +38,6 @@ In this way, the developer can easily figure out the functionality of each handl ## Mapping of the handlers -The full mapping of the handlers and their current paths and actions can be found [**here**](https://docs.dotkernel.org/img/api/v6/naming-convention.png). +The full mapping of the handlers and their current paths and actions can be found in the full [naming convention table](https://docs.dotkernel.org/img/api/v6/naming-convention.png). [![naming-convention-thumbnail](https://docs.dotkernel.org/img/api/v6/naming-convention-thumbnail.png)](https://docs.dotkernel.org/img/api/v6/naming-convention.png) diff --git a/docs/book/v6/introduction/introduction.md b/docs/book/v6/introduction/introduction.md index 4e7c6933..e32c69b0 100644 --- a/docs/book/v6/introduction/introduction.md +++ b/docs/book/v6/introduction/introduction.md @@ -29,7 +29,7 @@ Therefore, for every preflight request, there is at least one Router request. ## OAuth 2.0 OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts on your Dotkernel API. -We use [mezzio/mezzio-authentication-oauth2](https://github.com/mezzio/mezzio-authentication-oauth2) which provides OAuth 2.0 authentication for Mezzio and PSR-15 applications by using the [thephpleague/oauth2-server]https://github.com/thephpleague/oauth2-server package. +We use [mezzio/mezzio-authentication-oauth2](https://github.com/mezzio/mezzio-authentication-oauth2) which provides OAuth 2.0 authentication for Mezzio and PSR-15 applications by using the [thephpleague/oauth2-server](https://github.com/thephpleague/oauth2-server) package. ## Email diff --git a/docs/book/v6/openapi/write-documentation.md b/docs/book/v6/openapi/write-documentation.md index cc0da40c..9247ce54 100644 --- a/docs/book/v6/openapi/write-documentation.md +++ b/docs/book/v6/openapi/write-documentation.md @@ -107,4 +107,4 @@ To summarize, the typical scenario on working on your own instance of Dotkernel - create new module (example: `Book`) - add functionality to your new module (routes, entities, repositories, handlers, services, tests etc) - create file `OpenAPI.php` in the new module and describe each new endpoint -- generate latest version of documentation file as described [here](./generate-documentation.md) +- generate latest version of documentation file as described [in this tutorial](./generate-documentation.md) diff --git a/docs/book/v6/security/basic-security.md b/docs/book/v6/security/basic-security.md new file mode 100644 index 00000000..965872e1 --- /dev/null +++ b/docs/book/v6/security/basic-security.md @@ -0,0 +1,86 @@ +# Basic Security + +Dotkernel API provides all necessary tools to implement safe applications, however you will need to manually make use of some of them. +This section will go over the provided tools and any steps you need to follow in order to use them successfully, as well as a few general considerations. + +## User Input Validation + +In order to validate user input, Dotkernel API makes use of [laminas/laminas-inputfilter](https://github.com/laminas/laminas-inputfilter). +It is strongly recommended that custom functionality parsing user input also make use of input filters to validate the data. + +## Content Negotiation + +Content negotiation in Dotkernel API is done by a middleware configured using the `config/autoload/content-negotiation.global.php` file. + +Whenever an endpoint needs custom `Accept` and/or `Content-Type`, make sure that you set them in the above file. + +> Read more about [content negotiation](https://www.dotkernel.com/dotkernel-api/content-negotiation-in-dotkernel-rest-api/) and the way it is implemented in [Dotkernel API](../core-features/content-validation.md). + +## Cross-Origin Resource Sharing + +Dotkernel API uses [mezzio/mezzio-cors](https://github.com/mezzio/mezzio-cors) to handle CORS details. +The default configuration, found in `config/autoload/cors.local.php`, makes the application accessible by any origin. + +Make sure your application specifies only the required origins when in a production environment. + +> This step is described in the [CORS](../tutorials/cors.md) tutorial. + +## Role-Based Access Control + +This project makes use of [mezzio/mezzio-authorization-rbac](../core-features/authorization.md) to handle access control. + +The default use cases have already been configured, but any custom functionality will require additional configuration to make sure it is protected. +Update the configuration file of this package (`config/autoload/authorization.global.php`) whenever you add new routes or roles. + +## Demo Credentials + +Dotkernel API ships with two demo accounts: an admin account (`admin`) and a user account (`test@dotkernel.com`), +with public identities and passwords as described in the [token authentication tutorial](https://docs.dotkernel.org/api-documentation/v6/tutorials/token-authentication/). + +Make sure to **update** or **remove** these demo accounts in your production environment. + +## Error Reporting Endpoint and ErrorReportingTokens + +The error reporting endpoint (`/error-report`) is intended to be used by third parties to report errors back to your application. +This endpoint requires its own token type, namely an `ErrorReportingToken`, that is to be added in the configuration file for every application sending reports. + +Since these tokens do not have an expiration date, consider periodically refreshing them manually. + +This feature is configured using the `config/autoload/error-handling.global.php` file, under the configured `ErrorReportServiceInterface::class` key. + +This file is visible to your VCS by default, so take care not to overwrite tokens locally and commit them to your production environment. +Additionally, make sure the `ip_whitelist` or `domain_whitelist` keys are set to your desired values, especially when in a production environment. + +> Read more about the [error reporting](../core-features/error-reporting.md) feature. + +## OpenAPI Documentation + +In order to provide an interactive documentation, Dotkernel API implemented [zircote/swagger-php](https://github.com/zircote/swagger-php). + +Make sure **not** to include sensitive data as examples for any of the documented endpoints. +It is not recommended to enable the documentation in a production environment. + +> Read more about the [OpenAPI documentation](../openapi/introduction.md). + +## PHP Dependencies + +Dotkernel API uses `composer` to handle PHP dependencies. +In time, make sure to review any common vulnerabilities and exposures for your dependencies. + +> You may also keep an eye on the Dotkernel API changelog for any updates relevant to your project. + +## General Considerations + +- `*.global.php` and `*.php.dist` configuration files are visible to the VCS, make sure **not** to include sensitive data in commits. + - `*.local.php` configuration files are ignored by the VCS by default and are the recommended place for sensitive data such as API keys. +- Make sure the `development mode` is correctly set - **do not** enable `development mode` in a production environment. + - You can use the following command to check the current status: + +```shell +composer development-status +``` + +- Dotkernel API ships with a [Laminas Continuous Integration](https://github.com/laminas/laminas-continuous-integration-action) GitHub Action, + if you are using a public repository consider keeping it in your custom applications to ensure code quality. + +> Read more about using [Laminas Continuous Integration](https://getlaminas.org/blog/2024-08-05-using-laminas-continuous-integration.html). diff --git a/docs/book/v6/security/oauth2-security.md b/docs/book/v6/security/oauth2-security.md new file mode 100644 index 00000000..a1ead3ba --- /dev/null +++ b/docs/book/v6/security/oauth2-security.md @@ -0,0 +1,32 @@ +# OAuth2 Security + +Dotkernel API uses the [mezzio/mezzio-authentication-oauth2](https://github.com/mezzio/mezzio-authentication-oauth2) component to provide the OAuth2 authentication service. +As a security stating point, when developing an application using this project make sure you go over the following steps. + +## Default OAuth Clients + +The project ships with the default OAuth clients `admin` and `frontend` with passwords equal to their names, as described in the [Authentication](https://docs.dotkernel.org/api-documentation/v6/core-features/authentication/) guide. + +These clients **must not** remain unchanged in your production environment, as they are a security risk - +ensure you deleted them or updated the passwords. + +## OAuth Token Lifetime and Refresh Hygiene + +The configuration for OAuth2 tokens can be edited in `config/autoload/local.php` under the `authentication` key. + +By default, the lifetimes of the `access` and `refresh` tokens are set to one day and one month respectively. +Make sure to adjust their values in accordance to your application's needs, with lower values being generally safer. + +> If your application requires it, you can revoke user OAuth tokens before their expiration by making use of the `revokeTokens` method of `UserService`. +> Read more about the available [configuration options](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration). + +## Autogeneration of Cryptographic Keys + +Dotkernel API makes use of the `./vendor/bin/generate-oauth2-keys` command from `mezzio-authentication-oauth2` to automatically regenerate the +public/private key pair used to verify the transmitted JWTs. +This process is done after each `composer update` (or `composer install` with no lock file), as specified in `composer.json` under the `scripts.post-update-cmd` key. + +While hidden to the VCS by default, keep in mind not to commit any local keys. + +> Autogeneration of keys can be disabled by simply removing the `php ./vendor/bin/generate-oauth2-keys` command from the mentioned key. +> While not related to Dotkernel API itself, do ensure that the directory containing the keys is properly secured. diff --git a/mkdocs.yml b/mkdocs.yml index 980ca95d..39f73546 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -68,6 +68,9 @@ nav: - "Render Documentation": v6/openapi/render-documentation.md - "Use Documentation": v6/openapi/use-documentation.md - "Getting Help": v6/openapi/getting-help.md + - Basic Security: + - "Basic Security": v6/security/basic-security.md + - "OAuth2 Security": v6/security/oauth2-security.md - Reference: - "Anonymize Accounts": v6/reference/account-anonymization.md - v5: