docs: add description for logging

Author: kenjis

docs/addons/jwt.md

@@ -34,9 +34,9 @@ To use JWT Authentication, you need additional setup and configuration.
 
     ```php
     <?php
-    
+
     // app/Config/AuthJWT.php
-    
+
     declare(strict_types=1);
 
     namespace Config;
@@ -128,6 +128,19 @@ php -r 'echo base64_encode(random_bytes(32));'
 
     The secret key is used for signing and validating tokens.
 
+### Login Attempt Logging
+
+By default, only failed login attempts are recorded in the `auth_token_logins` table.
+
+```php
+public int $recordLoginAttempt = Auth::RECORD_LOGIN_ATTEMPT_FAILURE;
+```
+
+If you don't want any logs, set it to `Auth::RECORD_LOGIN_ATTEMPT_NONE`.
+
+If you want to log all login attempts, set it to `Auth::RECORD_LOGIN_ATTEMPT_ALL`.
+It means you log all requests.
+
 ## Issuing JWTs
 
 To use JWT Authentication, you need a controller that issues JWTs.
@@ -351,3 +364,14 @@ It uses the `secret` and `alg` in the `Config\AuthJWT::$keys['default']`.
 It sets the `Config\AuthJWT::$defaultClaims` to the token, and sets
 `"iat"` (Issued At) and `"exp"` (Expiration Time) claims automatically even if
 you don't pass them.
+
+## Logging
+
+Login attempts are recorded in the `auth_token_logins` table, according to the
+configuration above.
+
+When a failed login attempt is logged, the raw token value sent is saved in
+the `identifier` column.
+
+When a successful login attempt is logged, the SHA256 hash value of the token
+sent is saved in the `identifier` column.

docs/references/authentication/hmac.md

@@ -112,20 +112,6 @@ $token = $user->getHmacTokenById($id);
 $tokens = $user->hmacTokens();
 ```
 
-## HMAC Keys Lifetime
-
-HMAC Keys/Tokens will expire after a specified amount of time has passed since they have been used.
-This uses the same configuration value as AccessTokens.
-
-By default, this is set to 1 year. You can change this value by setting the `$unusedTokenLifetime`
-value in the **app/Config/AuthToken.php** config file. This is in seconds so that you can use the
-[time constants](https://codeigniter.com/user_guide/general/common_functions.html#time-constants)
-that CodeIgniter provides.
-
-```php
-public $unusedTokenLifetime = YEAR;
-```
-
 ## HMAC Keys Scopes
 
 Each token (set of keys) can be given one or more scopes they can be used within. These can be thought of as
@@ -219,3 +205,44 @@ authtoken.hmacEncryptionCurrentKey = k2
 Depending on the set length of the Secret Key and the type of encryption used, it is possible for the encrypted value to
 exceed the database column character limit of 255 characters. If this happens, creation of a new HMAC identity will
 throw a `RuntimeException`.
+
+## Configuration
+
+### HMAC Keys Lifetime
+
+HMAC Keys/Tokens will expire after a specified amount of time has passed since they have been used.
+This uses the same configuration value as AccessTokens.
+
+By default, this is set to 1 year. You can change this value by setting the `$unusedTokenLifetime`
+value in the **app/Config/AuthToken.php** config file. This is in seconds so that you can use the
+[time constants](https://codeigniter.com/user_guide/general/common_functions.html#time-constants)
+that CodeIgniter provides.
+
+```php
+public $unusedTokenLifetime = YEAR;
+```
+
+### Login Attempt Logging
+
+By default, only failed login attempts are recorded in the `auth_token_logins` table.
+This can be modified in the **app/Config/AuthToken.php** config file.
+
+```php
+public int $recordLoginAttempt = Auth::RECORD_LOGIN_ATTEMPT_FAILURE;
+```
+
+If you don't want any logs, set it to `Auth::RECORD_LOGIN_ATTEMPT_NONE`.
+
+If you want to log all login attempts, set it to `Auth::RECORD_LOGIN_ATTEMPT_ALL`.
+It means you log all requests.
+
+## Logging
+
+Login attempts are recorded in the `auth_token_logins` table, according to the
+configuration above.
+
+When a failed login attempt is logged, the raw token value sent is saved in
+the `identifier` column.
+
+When a successful login attempt is logged, the token name is saved in the
+`identifier` column.

docs/references/authentication/tokens.md

@@ -125,3 +125,30 @@ if ($user->tokenCant('forums.manage')) {
     // do something....
 }
 ```
+
+## Configuration
+
+### Login Attempt Logging
+
+By default, only failed login attempts are recorded in the `auth_token_logins` table.
+This can be modified in the **app/Config/AuthToken.php** config file.
+
+```php
+public int $recordLoginAttempt = Auth::RECORD_LOGIN_ATTEMPT_FAILURE;
+```
+
+If you don't want any logs, set it to `Auth::RECORD_LOGIN_ATTEMPT_NONE`.
+
+If you want to log all login attempts, set it to `Auth::RECORD_LOGIN_ATTEMPT_ALL`.
+It means you log all requests.
+
+## Logging
+
+Login attempts are recorded in the `auth_token_logins` table, according to the
+configuration above.
+
+When a failed login attempt is logged, the raw token value sent is saved in
+the `identifier` column.
+
+When a successful login attempt is logged, the token name is saved in the
+`identifier` column.