Post-Authentication Actions (2FA & Activation)
jengo/auth provides an extensible Action Pipeline allowing you to intercept authentication workflows for mandatory post-login challenges, such as Two-Factor Authentication (2FA) or Email Account Activation.
1. Two-Factor Authentication (Email2FA)
When 2FA is enabled for a user, jengo/auth interrupts the login session and redirects them to the action verification screen (action/show).
How it Works:
Email2FA::show()generates a cryptographically secure 6-digit verification code.- Sends the code to the user's email via your pluggable
NotificationSenderInterface. - Triggers the
mfaChallengeevent. - User submits the code. If valid and unexpired (5-minute TTL), authentication completes.
- Users can click Resend Code (POST
/action/challenge) to issue a fresh code or Cancel (POST/action/cancel) to abort and clear pending state.
Enabling in app/Config/Auth.php:
public array $actions = [
'login' => [
\Jengo\Auth\Actions\Email2FA::class,
],
];2. Account Activation (EmailActivator)
Requires newly registered users to verify their email via a 6-digit security code before gaining full application access.
How it Works:
- When registered, user account status is set to
pendingwithactive = 0. EmailActivator::show()generates a 6-digit activation code and sends an email notification.- User enters the code on the verification challenge screen.
- On verification, user record is updated to
active = 1and status becomesactive. - Supports resending fresh activation codes via
POST /action/challenge.
Enabling in app/Config/Auth.php:
public array $actions = [
'register' => [
\Jengo\Auth\Actions\EmailActivator::class,
],
];3. Creating Custom Actions
To build a custom action (e.g. Terms of Service Acceptance or Forced Password Reset), implement Jengo\Auth\Contracts\AuthActionInterface.
- If your action supports re-issuing challenges (e.g. resending SMS codes), use the
HasActionChallengetrait. - If your action can conditionally determine whether it is pending/required for the user, use the
HasActionPendingtrait:
<?php
declare(strict_types=1);
namespace App\Auth\Actions;
use CodeIgniter\HTTP\RequestInterface;
use CodeIgniter\HTTP\ResponseInterface;
use Jengo\Auth\Concerns\HasActionChallenge;
use Jengo\Auth\Concerns\HasActionPending;
use Jengo\Auth\Contracts\AuthActionInterface;
use Jengo\Auth\DTOs\AuthResponseData;
use Jengo\Auth\Entities\User;
class RequireTermsAcceptance implements AuthActionInterface
{
use HasActionChallenge;
use HasActionPending;
public function getActionName(): string
{
return 'terms_acceptance';
}
/**
* Determine if this action is required for the user.
* If false, the pipeline automatically skips this action and advances to the next action or finalizes login.
*/
public function isPending(RequestInterface $request, User $user): bool
{
return empty($user->terms_accepted_at);
}
public function show(RequestInterface $request, User $user): ResponseInterface
{
$data = new AuthResponseData(
action: 'action.show',
message: 'Please review and accept our updated Terms of Service.',
data: ['action' => 'terms_acceptance'],
user: $user
);
return auth()->renderResponse('action.show', $data, $request);
}
/**
* Optional: Re-issue or reset challenge state.
*/
public function challenge(RequestInterface $request, User $user): ResponseInterface
{
$data = new AuthResponseData(
action: 'action.challenge',
status: 'info',
message: 'Terms challenge refreshed.',
redirectTo: auth_url('auth.action.show'),
user: $user
);
return auth()->renderResponse('action.challenge', $data, $request);
}
public function verify(RequestInterface $request, User $user): bool
{
$accepted = (bool) ($request->getPost('accept_terms') ?? false);
if ($accepted) {
$user->terms_accepted_at = date('Y-m-d H:i:s');
auth()->getUserModel()->save($user);
return true;
}
return false;
}
}4. Conditional Actions & Skipping (HasActionPending)
Actions in jengo/auth can conditionally decide whether they are required for a user by using the HasActionPending trait and implementing isPending(RequestInterface $request, User $user): bool.
- On Login / Register: If
isPending()returnsfalsefor configured actions, the action is bypassed. If all configured actions returnfalse, the user is authenticated immediately with zero redirects or prompts. - Actions without
HasActionPending: Default to always pending (true). - During Multi-Action Pipelines: When advancing through actions, any action returning
falseforisPending()is automatically skipped, firing theactionSkippedevent and transitioning seamlessly to the next pending action.
5. Action-Specific View Resolution
You can customize the HTML view or Inertia component for specific actions in app/Config/Auth.php using the action's identifier:
// app/Config/Auth.php
public array $views = [
// Global fallback view for all action challenges:
'action_mfa' => 'Pages/Auth/DefaultActionChallenge',
// Action-specific view overrides (matched by getActionName()):
'action_email_2fa' => 'Pages/Auth/EmailTwoFactorChallenge',
'action_terms_acceptance' => 'Pages/Auth/TermsOfServiceModal',
'action_sms_otp' => 'App\Views\Auth\sms_otp_challenge',
];Resolution Priority Order
When rendering an action view:
- Explicit View on DTO:
$data->viewprovided directly by the action class. - Action-Specific Config Key:
config('Auth')->views['action_' . $actionName](oraction_mfa_{actionName}). - Global Action Fallback:
config('Auth')->views['action_mfa']. - Default Built-in View:
Jengo\Auth\Views\mfa_challenge(orauth/mfa_challengefor Inertia).
6. Cancelling Pending Actions
If a user wishes to cancel out of a pending authentication action, the route POST /action/cancel (auth.action.cancel) clears all pending session state (auth_pending_user_id, auth_pending_actions) and safely redirects back to the login screen.
