diff --git a/docs/book/v7/core-features/authentication.md b/docs/book/v7/core-features/authentication.md index 043ff80e..f9eefd8d 100644 --- a/docs/book/v7/core-features/authentication.md +++ b/docs/book/v7/core-features/authentication.md @@ -24,11 +24,46 @@ This allows users to exchange their credentials (username/password) for access t These tokens are then used for later requests instead of repeatedly sending credentials. Authentication in Dotkernel API is built around the `mezzio/mezzio-authentication-oauth2` component and is already configured out of the box. -To customize authentication behavior (token lifetimes, algorithms, etc.), edit `config/autoload/local.php` under the `authentication` key. +To customize authentication behavior (token lifetimes, algorithms, etc.), edit `config/autoload/authentication.global.php` under the `authentication` key. See the [Mezzio OAuth2 documentation](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration) for all available options. +> The `authentication.global.php` file applies from Dotkernel API versions after 7.2. +> In Dotkernel API 7.2 and earlier, the `authentication` key is in `config/autoload/local.php`. + > You can check the [mezzio/mezzio-authentication-oauth2](https://docs.mezzio.dev/mezzio-authentication-oauth2/v1/intro/#configuration) configuration part for more info. +### Token lifetime format + +The token lifetimes are set as [DateInterval](https://www.php.net/manual/en/dateinterval.construct.php) strings, under the `authentication` key in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier): + +| Key | Default | Controls | +|------------------------|---------|-------------------------------------------| +| `access_token_expire` | `P1D` | How long an access token is valid | +| `refresh_token_expire` | `P1M` | How long a refresh token is valid | +| `auth_code_expire` | `PT10M` | How long an authorization code is valid | + +A value is made of: + +- `P`, followed by date units: `D` days, `W` weeks, `M` months, `Y` years +- `PT`, followed by time units: `H` hours, `M` minutes, `S` seconds +- a number before each unit, e.g. `P2D` or `PT10M` + +Date and time units can be combined in one value, with the `T` separating them. + +Examples: + +| Value | Meaning | +|-----------|----------------------------| +| `P1D` | 1 day | +| `P1M` | 1 calendar month | +| `P30D` | exactly 30 days | +| `P2DT3H` | 2 days and 3 hours | +| `PT10M` | 10 minutes | +| `PT3600S` | 3600 seconds (1 hour) | + +> `P1M` is a calendar month, so its length in days depends on the month it starts in. +> Use `P30D` if the lifetime must be exactly 30 days. + ## How it works Dotkernel API authentication system can be used for SPAs (single-page applications), mobile applications, and simple, token-based APIs. @@ -226,7 +261,7 @@ The client values come from `oauth_clients` and the scope from `oauth_scopes`. **Q: How long do the tokens last?** -A: Access tokens expire after one day and refresh tokens after one month, both configurable under the `authentication` key in `config/autoload/local.php`. +A: Access tokens expire after one day and refresh tokens after one month, both configurable under the `authentication` key in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier), see [Token lifetime format](#token-lifetime-format). **Q: How do I renew an expired access token?** diff --git a/docs/book/v7/introduction/file-structure.md b/docs/book/v7/introduction/file-structure.md index bc42d952..0ffb47cc 100644 --- a/docs/book/v7/introduction/file-structure.md +++ b/docs/book/v7/introduction/file-structure.md @@ -50,6 +50,7 @@ This folder contains all application-related config files: This folder contains all service-related local and global config files: +* `authentication.global.php` - Configures OAuth2 authentication: key paths, token lifetimes and the invalid credentials message (added after 7.2; in 7.2 and earlier this lives in `local.php`) * `authorization.global.php` - Configures access per route for user roles * `cli.global.php` - Configures cli * `content-negotiation.global.php` - Configures request and response formats @@ -57,7 +58,7 @@ This folder contains all service-related local and global config files: * `dependencies.global.php` - Sets global dependencies that should be accessible by all modules * `development.local.php.dist` - Gets symlinked into place when enabling development mode; activates error handlers * `error-handling.global.php` - Configures and activates error logs -* `local.php.dist` - Local configuration file: database credentials, application name and URL, OAuth2 key paths +* `local.php.dist` - Local configuration file: database credentials, application name and URL (in 7.2 and earlier, also the OAuth2 key paths) * `local.test.php.dist` - Local configuration for functional tests * `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging. Not committed: the post-install script copies it out of `dotkernel/dot-mail` during installation (in 7.0 this file is `mail.global.php`) * `mezzio.global.php` - Mezzio core config file diff --git a/docs/book/v7/introduction/introduction.md b/docs/book/v7/introduction/introduction.md index 85ba5394..e7b67685 100644 --- a/docs/book/v7/introduction/introduction.md +++ b/docs/book/v7/introduction/introduction.md @@ -29,7 +29,7 @@ Below is a quick overview of features in Dotkernel API and how they interconnect | Feature | Purpose | Configuration | |---------------------|------------------------------------|------------------------------------------------| -| OAuth2 | Authentication | config/autoload/local.php | +| OAuth2 | Authentication | config/autoload/authentication.global.php | | RBAC | Authorization | config/autoload/authorization.global.php | | Content Negotiation | Request/response format validation | config/autoload/content-negotiation.global.php | | OpenAPI/Swagger | API documentation | Auto-generated | @@ -148,7 +148,7 @@ A: REST APIs in a microservices setup, headless CMS backends, e-commerce and Saa **Q: Where do I configure each feature?** -A: OAuth2 in `config/autoload/local.php`, RBAC in `config/autoload/authorization.global.php`, content negotiation in `config/autoload/content-negotiation.global.php`; the OpenAPI documentation is generated by `composer openapi` and configured in `config/autoload/openapi.global.php`. +A: OAuth2 in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier), RBAC in `config/autoload/authorization.global.php`, content negotiation in `config/autoload/content-negotiation.global.php`; the OpenAPI documentation is generated by `composer openapi` and configured in `config/autoload/openapi.global.php`. **Q: How do I register a new module?** diff --git a/docs/book/v7/security/oauth2-security.md b/docs/book/v7/security/oauth2-security.md index 2252ecb3..09c70acb 100644 --- a/docs/book/v7/security/oauth2-security.md +++ b/docs/book/v7/security/oauth2-security.md @@ -17,7 +17,8 @@ These clients **must not** remain unchanged in your production environment, as t ## OAuth Token Lifetime and Refresh Hygiene -The configuration for OAuth2 tokens can be edited in `config/autoload/local.php` under the `authentication` key. +The configuration for OAuth2 tokens can be edited in `config/autoload/authentication.global.php` under the `authentication` key (`config/autoload/local.php` in 7.2 and earlier). +The values use the `DateInterval` format, explained in [Token lifetime format](../core-features/authentication.md#token-lifetime-format). 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 with your application's needs, with lower values being generally safer. @@ -67,7 +68,7 @@ They ship with passwords equal to their names, so leaving them in place hands an **Q: Where do I change token lifetimes?** -A: Under the `authentication` key in `config/autoload/local.php`. +A: Under the `authentication` key in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier), using the [DateInterval format](../core-features/authentication.md#token-lifetime-format). Defaults are one day for access tokens and one month for refresh tokens; shorter values are generally safer. **Q: Can I invalidate a user's tokens before they expire?** diff --git a/docs/book/v7/tutorials/token-authentication.md b/docs/book/v7/tutorials/token-authentication.md index b93db455..b21df562 100644 --- a/docs/book/v7/tutorials/token-authentication.md +++ b/docs/book/v7/tutorials/token-authentication.md @@ -152,7 +152,7 @@ You should see a `200 OK` response with the following JSON body: Field description: - `token_type`: token type to be set when sending the `Authorization` header (example: `Authorization: Bearer eyJ0e...`) -- `expires_in`: access token lifetime (modify in: `config/autoload/local.php` > `authentication`.`access_token_expire`) +- `expires_in`: access token lifetime (modify in: `config/autoload/authentication.global.php` > `authentication`.`access_token_expire`; `config/autoload/local.php` in 7.2 and earlier) - `access_token`: generated access token (store it for later use) - `refresh_token`: generated refresh token (store it for regenerating expired access token) @@ -256,7 +256,7 @@ You should see a `200 OK` response with the following JSON body: Field description: - `token_type`: token type to be set when sending the `Authorization` header (example: `Authorization: Bearer eyJ0e...`) -- `expires_in`: access token lifetime (change here: `config/autoload/local.php` `authentication`->`access_token_expire`) +- `expires_in`: access token lifetime (change here: `config/autoload/authentication.global.php` `authentication`->`access_token_expire`; `config/autoload/local.php` in 7.2 and earlier) - `access_token`: generated access token (store it for later use) - `refresh_token`: generated refresh token (store it for regenerating expired access token) @@ -392,7 +392,7 @@ A: Generating uses `grant_type: password` with a username and password; refreshi **Q: How long is an access token valid?** -A: 86400 seconds — one day — configurable via `authentication`, `access_token_expire` in `config/autoload/local.php`. +A: 86400 seconds — one day — configurable via `authentication`, `access_token_expire` in `config/autoload/authentication.global.php` (`config/autoload/local.php` in 7.2 and earlier). **Q: I get `400 Bad Request` with "Invalid credentials". What should I check?**