diff --git a/docs/book/v7/security/2fa-with-totp.md b/docs/book/v7/security/2fa-with-totp.md new file mode 100644 index 0000000..aaeba76 --- /dev/null +++ b/docs/book/v7/security/2fa-with-totp.md @@ -0,0 +1,33 @@ +# Time-based One-Time Password (TOTP) + +A **Time-based One-Time Password (TOTP)** is a security algorithm used as part of **two-factor authentication (2FA)** to protect against account attacks. + +The mechanism is integrated into [dot-totp](https://github.com/dotkernel/dot-totp) to enhance security by requiring both a **password** and **an additional one-time code**. +Our implementation follows the industry standard of using an Authenticator app to generate temporary, unique 6-digit codes that change every 30 seconds. + +## 2FA with TOTP Flow + +Below is a simplified flow for the 2FA with a TOTP mechanism. + +```mermaid +sequenceDiagram + participant U as 👤 User + participant A as 📱 Authenticator App + participant S as 🖥 Server + + U->>S: 1. Enter username + password + S->>S: 2. Verify credentials + + S-->>U: 3. Request TOTP code + + A->>U: 4. Display TOTP (time-based) + U->>S: 5. Submit TOTP code + + S->>S: 6. Validate (shared secret + time) + + S-->>U: 7. ✅ Access granted +``` + +## Next Steps + +[Install 2FA with dot-totp](../configuring-2fa-with-totp.md). diff --git a/docs/book/v7/tutorials/install-dot-totp.md b/docs/book/v7/tutorials/install-dot-totp.md new file mode 100644 index 0000000..1b0700a --- /dev/null +++ b/docs/book/v7/tutorials/install-dot-totp.md @@ -0,0 +1,81 @@ +# Installing dot-totp into Dotkernel Admin + +If you haven't already, install [Dotkernel Admin](https://github.com/dotkernel/admin). + +> The installation steps listed below should work similarly in any middleware-based application. + +The first step is to include the package in your project by running this command: + +```shell +composer require dotkernel/dot-totp +``` + +We will follow the Dotkernel file structure and create the files in the list below. +If you follow the links from the [main totp integration example](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp), you can download the files and add them to your codebase. + +- [src/Admin/src/Form/RecoveryForm.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Form/RecoveryForm.php) +- [src/Admin/src/Form/TotpForm.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Form/TotpForm.php) +- [src/Admin/src/Handler/Account/GetDisableTotpFormHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetDisableTotpFormHandler.php) +- [src/Admin/src/Handler/Account/GetEnableTotpFormHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetEnableTotpFormHandler.php) +- [src/Admin/src/Handler/Account/GetRecoveryFormHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetRecoveryFormHandler.php) +- [src/Admin/src/Handler/Account/GetTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/GetTotpHandler.php) +- [src/Admin/src/Handler/Account/PostDisableTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostDisableTotpHandler.php) +- [src/Admin/src/Handler/Account/PostEnableTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostEnableTotpHandler.php) +- [src/Admin/src/Handler/Account/PostValidateRecoveryHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostValidateRecoveryHandler.php) +- [src/Admin/src/Handler/Account/PostValidateTotpHandler.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/src/Handler/Account/PostValidateTotpHandler.php) +- [src/Admin/templates/admin/recovery-form.html.twig](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Admin/templates/admin/recovery-form.html.twig) +- [src/App/src/Middleware/CancelUrlMiddleware.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/App/src/Middleware/CancelUrlMiddleware.php) +- [src/App/src/Middleware/TotpMiddleware.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/App/src/Middleware/TotpMiddleware.php) + +You can use the trait at [src/Core/src/App/src/Entity/TotpTrait.php](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/src/Core/src/App/src/Entity/TotpTrait.php) in any entity where you need 2FA. + +> Make sure to migrate the new columns `totpSecret`, `totp_enabled` and `recovery_codes` in your entity. + +There are still some code snippets in the [_misc](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp) folder: + +- [the enable/disable 2FA button](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-view-account.html.twig) should be used in the `view-account.html.twig` file or in a new page. +- [the routes updates](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-routes.php) must be added in the `src/Admin/src/RoutesDelegator.php` file. +- [the pipeline updates](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-Pipeline.php) must be added in the `config/pipeline.php` file after `$app->pipe(AuthMiddleware::class);`. +- [the ConfigProvider updates](https://github.com/dotkernel/admin-documentation/tree/main/code_examples/totp/_misc/totp-append-ConfigProvider.php) must be added in the `src/Admin/src/ConfigProvider.php` file. + +## Dot-totp in Action + +Once you have `dot-totp` implemented, you can activate the feature in your admin accounts. +If you navigate to your profile from the top-right image in Dotkernel Admin, you should see this box. + +![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/profile-totp-deactivated.jpg) + +Simply click on 'Enable TOTP' to begin the activation process. + +> We blurred out the QR code and recovery codes for this tutorial. +> You will receive dynamically generated versions that will be fully visible to you. + +> You will need to have an Authenticator app installed on your mobile device. + +![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/totp-activate-qr.jpg) + +Follow the instructions on the screen: + +- Scan the QR code with your mobile device. +- Enter the 6-digit code it generates on your mobile device. + +> The code refreshes every 30 seconds. + +The TOPT activation flow will list several recovery codes you can use if your mobile device isn't available. + +![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/totp-recovery-codes.jpg) + +> Each recovery code is usable only once. + +> Save the recovery codes in a secure location. + +If the code is valid, you will be logged in, and TOTP will be activated for your account. + +Whenever you need to log into the account, you will start by entering your username and password, like before. +Since TOTP is activated, you will need to also submit the code from your Authenticator app. +Alternatively, you can submit a recovery code. + +![Dotkernel Admin File Structure!](https://docs.dotkernel.org/img/admin/v7/install-totp/totp-ask-code.jpg) + +That's it! +You are now logged in securely. diff --git a/mkdocs.yml b/mkdocs.yml index 1efa0d0..d90ca17 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -35,8 +35,10 @@ nav: - "Set Up CSRF": v7/how-to/csrf.md - Security: - "Basic Security": v7/security/basic-security.md + - "Two Factor Authorization with Time-based One-Time Password": v7/security/2fa-with-totp.md - Tutorials: - "Creating a book module using DotMaker": v7/tutorials/create-book-module-via-dot-maker.md + - "Installing dot-totp": v7/tutorials/install-dot-totp.md - v6: - Introduction: v6/introduction/introduction.md - Overview: