CakeDC Users Plugin Documentation

The CakeDC Users plugin provides a complete user management system for CakePHP applications. Key capabilities include:

• User Lifecycle: Registration, email validation, profile management, and password reset.
• Authentication: Login/Logout, "Remember Me" (Cookie), and Magic Link (one-click login).
• Social Login: Support for Facebook, Twitter, Instagram, Google, LinkedIn (via OpenID Connect), Amazon, and GitHub.
• Security & 2FA: Two-Factor Authentication via One-Time Password (OTP) or Webauthn (e.g., Yubico Key, TouchID), account lockout policies, password strength meters, and reCaptcha (v2/v3).
• Authorization: Integrated Role-Based Access Control (RBAC) and Superuser support (requires CakeDC/auth).
• Admin Management: Built-in CRUD functionality for managing users.

The CakeDC Users plugin provides a comprehensive suite of authentication and user management capabilities, including:

• Registration & Verification: User registration and account verification via email tokens.
• Authentication: Standard email/password login, 'Remember Me' functionality via cookies, and Two-Factor Authentication (2FA).
• Social Login: Support for Twitter, Facebook, Google, and Instagram.
• Account Recovery: Password reset workflows using email-based tokens.
• User Management: Administrative capabilities to add, edit, and delete users.
• Authorization: Simple roles management, RBAC (Role-Based Access Control), and SuperUser authorization.
• Security: reCaptcha integration for registration and login endpoints.

Social authentication relies on a combination of middlewares and authenticators:

1. SocialAuthMiddleware + CakeDC/Users.Social (Authenticator): The primary flow used to redirect users to the provider and handle standard authentication.
2. SocialEmailMiddleware + CakeDC/Users.SocialPendingEmail (Authenticator): Used when the social provider does not return the user's email address, triggering a flow to collect/validate it.

When enabled, the plugin integrates OTP authentication into the login flow.

1. First-time setup: The user is presented with a QR code. They must scan this code using a Google Authenticator app (or similar TOTP app) to add your site.
2. Verification: After providing credentials, the user is prompted to enter the current validation code generated by their authenticator app to complete the login.

The plugin uses cakephp/authentication and cakephp/authorization by default. Most configuration is handled under the Auth key in config/users.php.

To disable the automatic loading of the authorization service, use:

'Auth.Authorization.enable' => false,

For detailed configuration of the underlying authentication/authorization logic, refer to their respective documentation or the plugin's internal configuration file at vendor/cakedc/users/config/users.php.

The CakeDC Users plugin uses two primary policies to perform permission checks for all requests:

1. Superuser policy: Allows the superuser to access any page regardless of other rules.
2. Rbac (Role-Based Access Control) policy: Allows you to define specific rules in config/permissions.php to perform checks based on request information (such as prefix, plugin, controller, and action) and user data (such as role).

Webauthn 2FA requires users to use a secure device compatible with the Web Authentication API (such as a Yubikey) during the login process.

When a user logs in for the first time with this feature enabled, they are required to register their secure device before they can use it for subsequent authentications.

The Users plugin is designed as a base for your application. You should not use it exactly as-is, but rather extend its core components to fit your specific business logic.

You can extend:

• The Model: Customize the Table and Entity classes.
• The Controller: Add custom logic to user management actions.
• The Templates: Override default views by placing them in templates/plugin/CakeDC/Users/Users.

For detailed instructions on how to perform these extensions, refer to the Extending the Plugin guide.

To enable reCaptcha, register your site at the Google reCaptcha console, install the google/recaptcha package, and add the following keys to config/users.php:

composer require google/recaptcha:@stable

'Users.reCaptcha.key' => 'YOUR RECAPTCHA KEY',
'Users.reCaptcha.secret' => 'YOUR RECAPTCHA SECRET',
'Users.reCaptcha.version' => '2', // Use '3' for version 3 (recommended)
'Users.reCaptcha.registration' => true, // Enable on registration
'Users.reCaptcha.login' => true, // Enable on login