Download the PHP package triopsi/simple-two-factor without Composer

SimpleTwoFactor Plugin for CakePHP 4

This plugin provides a simple two-factor authentication (2FA) mechanism for CakePHP 4 applications. It uses the RobThree/TwoFactorAuth library to handle the generation and verification of 2FA codes.

• SimpleTwoFactor Plugin for CakePHP 4
  • Features
  • Requirements
  • Two-Factor Authentication (2FA) Workflow
  • Workflow Overview
  • Technical Details
  • Installation
  • Configuration
  • 1. User Secret Store
  • 2. Load the Plugin
  • 3. Add Middleware
    • Middleware Options
    • Example Configuration in Application.php
    • 4. Example Controller Action
    • 5. Example View
  • SimpleTwoFactorComponent for CakePHP 4
  • Features
  • Load the Component
  • Generating a QR Code
  • Example View
  • Bugs \& Feedback
  • License

Features

• Easy Integration: Seamlessly integrates with CakePHP 4's authentication system.
• Configurable: Provides multiple configuration options to customize the 2FA process.
• Middleware Support: Includes middleware to enforce 2FA on specific routes.
• QR Code Generation: Supports QR code generation for easy setup with 2FA apps.
• Customizable Views: Allows customization of the 2FA verification form.
• Session Management: Manages 2FA verification status using session keys.
• Multiple Algorithms: Supports various algorithms for generating 2FA codes (SHA1, SHA256, SHA512, MD5).
• Flexible Providers: Supports different QR code and random number generator providers.
• Security: Enhances security by adding an additional layer of authentication.

Requirements

• CakePHP 4.*
• PHP 8.2

Two-Factor Authentication (2FA) Workflow

Two-Factor Authentication adds an additional layer of security to the authentication process by requiring not only a username and password but also a unique code generated by an authentication app.

Workflow Overview

1. User Registration with 2FA Setup

   • After registering or editing their profile, the user is presented with a QR code.
   • The QR code contains a secret key.
   • The user scans the QR code using an authentication app (e.g., Google Authenticator, Authy).
   • This generates a secret pair shared between the server and the user’s device.

2. Subsequent Logins

   • After entering the correct username and password, the user is prompted for a Two-Factor Authentication (2FA) code.
   • The user opens the authentication app to retrieve the current TOTP (Time-based One-Time Password).
   • The TOTP code is submitted to the server.
3. Verification and Access
   • The server verifies the TOTP code using the shared secret.
   • If the code is correct and matches the expected value, the user is granted access to the application.
   • If the code is incorrect, access is denied.

Technical Details

• QR Code Generation: The server generates a QR code containing the secret.
• Secret Storage: The secret is securely stored in the user database.
• TOTP Code Verification: At each login, the server uses the stored secret to verify the TOTP code submitted by the user.

This process ensures that even if a user's primary credentials are compromised, unauthorized access is prevented without the second factor of authentication.

Installation

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

Configuration

1. User Secret Store

To save the secret and to assign the user. The plugin requires a secret field in the user table. This could look as follows:

or via migration:

2. Load the Plugin

Load the plugin in your Application.php file:

Alternatively, execute the following line:

3. Add Middleware

Add the TwoFactorMiddleware to your middleware queue in src/Application.php. Make sure to add it directly under the AuthenticationMiddleware.

Middleware Options

The TwoFactorMiddleware class provides several configuration options that can be customized to fit your application's needs. Below are the available options along with their explanations:

• userSessionKey: The session key to store the user in. Default is 'Auth'.
• codeField: The field name in the request that contains the 2FA code. Default is 'code'.
• redirectUrl: The URL to redirect unauthenticated users to. Default is '/users/verifytfa'.
• sessionKeyVerified: The session key to store the 2FA verified status. Default is '2fa_verified'.
• userKeySecret: The user key to store the 2FA secret. Default is '_2tfa'.
• isEnabled2faProperty: The user key to check if 2FA is enabled. Default is 'secret_2tfa'.
• urlChecker: The URL checker config. Default is 'Authentication.Default'.
• issuer: The issuer name displayed in the 2FA app. Default is null.
• digits: The number of digits in the 2FA code. Default is 6.
• period: The number of seconds a 2FA code is valid. Default is 30.
• algorithm: The algorithm used for generating the 2FA code. Options are 'sha1', 'sha256', 'sha512', 'md5'. Default is 'sha1'.
• qrcodeprovider: The QR code provider. Options are 'BaconQrCodeProvider', 'EndroidQrCodeProvider'. Default is 'BaconQrCodeProvider'.
• rngprovider: The random number generator provider. Default is null.
• timeprovider: The time provider. Default is null.

Example Configuration in Application.php

To configure the TwoFactorMiddleware in your CakePHP application, you need to set the options in the middleware method of your Application.php file.

! It is important that the TwoFactorMiddleware is placed after the AuthenticationMiddleware. If the order is incorrect, the plugin cannot work properly.

4. Example Controller Action

Create a method in your UsersController to handle the 2FA verification.

Example for UsersController.php

5. Example View

Create a view for the 2FA verification form.

Example for verifytfa.php

SimpleTwoFactorComponent for CakePHP 4

The SimpleTwoFactorComponent provides methods to handle Two-Factor Authentication (2FA) in your CakePHP 4 application. This component allows you to generate secrets, verify codes, and create QR codes for easy setup with 2FA apps.

Features

• Generate 2FA Secrets: Create unique secrets for each user.
• Verify 2FA Codes: Verify the one-time codes generated by 2FA apps.
• Generate QR Codes: Generate QR codes for easy setup with 2FA apps.

Load the Component

Load the SimpleTwoFactorComponent in your controller:

Generating a QR Code

To generate a QR code for the user to scan with their 2FA app, you need to create a secret and then generate the QR code image.

Example View

Create a view for the 2FA setup form where the user can scan the QR code.

Example for setup2fa.php

Bugs & Feedback

https://github.com/triopsi/SimpleTwoFactor/issues

License

Copyright (c) 2025, Triopsi and licensed under The MIT License.

• CakePHP
• RobThree/TwoFactorAuth