mainul / password-policy
A Laravel package for password policy enforcement: validation rules, expiry, and reuse prevention
Requires
- php: ^8.2
- illuminate/auth: ^10.0|^11.0|^12.0|^13.0
- illuminate/console: ^10.0|^11.0|^12.0|^13.0
- illuminate/database: ^10.0|^11.0|^12.0|^13.0
- illuminate/hashing: ^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^10.0|^11.0|^12.0|^13.0
- illuminate/mail: ^10.0|^11.0|^12.0|^13.0
- illuminate/routing: ^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^10.0|^11.0|^12.0|^13.0
- illuminate/validation: ^10.0|^11.0|^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
- phpunit/phpunit: ^10.0|^11.0|^12.0
Suggests
- laravel/passport: Alternative API authentication: set api.guard to your passport guard.
- laravel/sanctum: Default authentication guard for the JSON API (api.guard = sanctum).
- xenon/laravelbdsms: Required to deliver temporary passwords by SMS when a user has no company email (policy 3.1.3).
Provides
None
Conflicts
None
Replaces
None
README
Language / ভাষা: English · বাংলা
English Documentation
A Laravel package for enforcing password and account security controls: validation rules, expiry, history, lockout, temporary passwords, MFA, audit logging, service accounts and a JSON API.
Requires PHP 8.2+ and Laravel 10 to 13.
The package supplies the controls. Several only take effect once you wire them into your application (middleware, login action, gates). Each section below shows exactly how, and the compliance table says which controls need wiring.
Table of contents
- Features
- Installation
- Quick start (10 minutes)
- Feature guide
- 1. Password rules
- 2. Password history (no reuse)
- 3. Current-password confirmation
- 4. Password expiry
- 5. Temporary passwords
- 6. Account lockout
- 7. Disable, enable and compromise
- 8. Session termination
- 9. Password reset protection
- 10. Authenticator-app MFA (TOTP)
- 11. Custom MFA driver
- 12. Admin accounts
- 13. Service accounts and rotation
- 14. Offboarding leavers
- 15. Audit log
- 16. Unusual-login detection
- 17. Secure transport (HTTPS)
- 18. Default-password scan
- JSON API
- Complete example: fresh Laravel project (MVC)
- Artisan commands
- Events
- Configuration reference
- Things to know before relying on it
- Policy compliance
- Testing · Upgrading · License
Features
- Password rules: length, upper/lower case, number, special character, personal-information check, banned words and pattern detection. Admins get stricter rules.
- Password history: blocks reuse of recent passwords.
- Temporary passwords: random, delivered by approved email/SMS only, change forced at first login.
- Account lockout: tiered lock periods, administrator unlock, rapid-failure (IP burst) detection.
- Password expiry: prompts users and disables overdue accounts automatically.
- Session termination: ends web sessions and API tokens after a password change, compromise or offboarding.
- Audit logging and monitoring: records security events, redacts secrets, detects unusual logins.
- Multi-factor authentication: built-in authenticator app (TOTP) or your own driver.
- Reset protection: one-time identity codes and role-based reset restrictions.
- Service accounts: owner, purpose, scheduled rotation through your vault.
- Offboarding and commands: disable leavers, flag shared credentials, diagnostics.
- JSON API: everything above over HTTP for mobile apps and SPAs (Sanctum by default, Passport supported).
Installation
composer require mainul/password-policy
php artisan vendor:publish --tag=password-policy-config
php artisan migrate # the package loads its own migrations
php artisan password-policy:check
The service provider is auto-discovered. Optional extras:
| Package | Why |
|---|---|
bacon/bacon-qr-code |
Shows a QR code on the authenticator set-up page (otherwise the key is shown). |
xenon/laravelbdsms |
Delivers temporary passwords and reset codes by SMS when a user has no company email. |
laravel/sanctum |
Default guard for the JSON API. |
laravel/passport |
Alternative API guard. |
Publishable assets:
php artisan vendor:publish --tag=password-policy-config # config/password-policy.php php artisan vendor:publish --tag=password-policy-migrations # copy migrations to edit them php artisan vendor:publish --tag=password-policy-views # restyle the MFA pages
Database changes. Migrations add these users columns: password_changed_at, must_change_password,
disabled_at, disabled_reason, locked_until, failed_login_count, lockout_level, is_permanently_locked,
requires_identity_verification, last_failed_login_at, session_version. They also create the tables
password_histories, password_audit_logs, known_logins, password_reset_codes, service_accounts,
mfa_credentials and password_policy_settings. The table name users is fixed. Existing users get
password_changed_at set to the migration time so they are not expired immediately.
Quick start
The minimum wiring for a typical Laravel app.
1. User model — add the trait and hide the password:
use Illuminate\Foundation\Auth\User as Authenticatable; use Mainul\PasswordPolicy\Traits\HasPasswordPolicy; class User extends Authenticatable { use HasPasswordPolicy; protected $hidden = ['password', 'remember_token']; }
The trait records password history, stamps password_changed_at, clears or sets the forced-change flag,
ends the user's other sessions after a change and writes the audit entry. It also gives you:
$user->passwordExpired(); // bool $user->mustChangePassword(); // bool (temporary password in use) $user->hasUsedPassword('Candidate#1'); // bool, checks the history $user->passwordHistories; // HasMany relation $user->setTemporaryPassword($hash)->save(); // see "Temporary passwords"
The package reads
config('password-policy.user_model')(defaultApp\Models\User). Change it if your model lives elsewhere.
2. Routes — attach the middleware (all are aliased by the package):
// routes/web.php Route::middleware(['auth', 'password.account_active', 'password.session_version', 'password.expiry', 'password.force_change', 'password.mfa']) ->group(function () { Route::get('/dashboard', DashboardController::class); // ... }); // Routes that must stay reachable so the user can fix the problem: Route::middleware('auth')->group(function () { Route::get('/password/change', [PasswordController::class, 'edit'])->name('password.change'); Route::put('/password', [PasswordController::class, 'update'])->name('password.update'); }); Route::middleware('password.secure')->group(function () { // HTTPS + no secrets in the URL Route::post('/login', [LoginController::class, 'store']); Route::post('/forgot-password', ...)->middleware('password.block_self_reset'); Route::post('/reset-password', ...); });
| Alias | Put it on | What it does | Policy |
|---|---|---|---|
password.expiry |
authenticated routes | Redirects (or 403 password_expired for JSON) when the password has expired |
3.5.1 |
password.force_change |
authenticated routes | Blocks everything until a temporary password is replaced | 3.1.5 |
password.account_active |
authenticated routes | Logs out disabled or overdue accounts | 3.4.2, 3.5.1, 3.8.3 |
password.session_version |
authenticated routes | Invalidates sessions older than the last forced termination | 3.5.2, 3.8.4 |
password.mfa |
authenticated routes | Requires the second factor | 3.4.3, 3.4.4, 3.9.2 |
password.secure |
login, password, reset routes | HTTPS only, no passwords in query strings | 3.3 |
password.block_self_reset |
forgot/reset-password routes | Blocks restricted roles from self-reset | 3.6.6 |
Routes named in middleware.excluded_routes (default password.change, password.update, logout) and
paths in middleware.excluded_paths are skipped by the expiry and forced-change checks. Make sure your
change-password routes use those names (or add yours to the config).
3. Login action — call the guard before checking credentials:
use Mainul\PasswordPolicy\Exceptions\AccountLockedException; use Mainul\PasswordPolicy\Services\LoginGuard; public function store(Request $request) { try { app(LoginGuard::class)->ensureCanAttempt($request->input('email')); } catch (AccountLockedException $e) { // One generic message for locked, disabled and expired accounts. return back()->withErrors(['email' => $e->getMessage()]); } if (! Auth::attempt($request->only('email', 'password'), $request->boolean('remember'))) { return back()->withErrors(['email' => 'These credentials do not match our records.']); } $request->session()->regenerate(); return redirect()->intended('/dashboard'); }
Laravel's Failed and Login events feed the lockout counters and audit log automatically.
4. Change-password form — validate with the package rules:
use Mainul\PasswordPolicy\Rules\{CurrentPasswordRule, PasswordNotReusedRule, PasswordPolicyRule}; public function update(Request $request) { $user = $request->user(); $request->validate([ // Rule objects are skipped for missing fields, so also mark the field `required`. 'current_password' => ['required', new CurrentPasswordRule($user)], 'password' => ['required', 'confirmed', PasswordPolicyRule::for($user), // admins get stricter rules new PasswordNotReusedRule($user)], ]); $user->update(['password' => Hash::make($request->password)]); // The trait stores history, stamps the date, audits, and ends other sessions. return redirect('/dashboard')->with('status', 'Password changed.'); }
5. Schedule — password-policy:disable-expired is scheduled daily automatically. Add the others yourself:
// routes/console.php (Laravel 11+) or app/Console/Kernel.php Schedule::command('password-policy:rotation-due --notify')->daily();
6. Gates — audit-log and API-admin access is denied to everyone until you define it:
// app/Providers/AppServiceProvider.php Gate::define('view-password-audit-logs', fn ($user) => $user->isSecurityOfficer());
Feature guide
1. Password rules
PasswordPolicyRule checks a candidate password against config('password-policy.rules').
| Config key | Default | Effect |
|---|---|---|
rules.min_length |
11 |
Minimum characters |
rules.require_uppercase / lowercase / numeric / special |
true |
Required character classes |
rules.forbid_personal_info |
true |
Rejects name parts, email local part, phone number, birthdate (needs a user) |
rules.banned_words |
['password','welcome','admin','qwerty','letmein','changeme'] |
Rejects passwords containing any word (case-insensitive) |
rules.forbid_patterns |
true |
Rejects 4+ repeated (aaaa) or sequential (1234, abcd, dcba) characters |
Usage in a Form Request or controller:
use Mainul\PasswordPolicy\Rules\PasswordPolicyRule; // Without a user: global rules; the personal-info check is skipped. $request->validate(['password' => ['required', new PasswordPolicyRule()]]); // With a user: admin accounts get the stricter admin rules + personal-info check. $request->validate(['password' => ['required', PasswordPolicyRule::for($request->user())]]);
Registration (no user yet). Use the string alias and (optionally) the personal-info check after creating the record:
$request->validate(['password' => ['required', 'confirmed', 'password_policy']]);
Custom messages. The failure message lists what is missing:
The password must contain at least 11 characters, one special character. To customise, pass your own message
for the rule in your lang file or build the check in a closure using (new PasswordPolicyRule($user))->passes('password', $value).
Configure the banned list with company terms in config/password-policy.php:
'rules' => [ 'min_length' => 12, 'banned_words' => ['password', 'welcome', 'acme', 'summer2024'], ],
The birthdate is read from columns.birthdate (default date_of_birth); name, email and phone columns come from
columns.*.
Quick check from Tinker:
(new PasswordPolicyRule())->passes('password', 'Abcd1234!x'); // false, pattern "abcd"/"1234" (new PasswordPolicyRule())->passes('password', 'Tr1cky#Horse9'); // true
2. Password history (no reuse)
Enabled by default (history.enabled, history.max_reuse_count = 5). The trait saves the old hash to
password_histories on every change; PasswordNotReusedRule compares a new plain password against the last N.
use Mainul\PasswordPolicy\Rules\PasswordNotReusedRule; $request->validate([ 'password' => ['required', new PasswordNotReusedRule($user)], ]); // Programmatic check: if ($user->hasUsedPassword($request->password)) { // reject }
Admins can have a different count via admin.history_count; the stricter value applies.
3. Current-password confirmation
Voluntary changes must prove knowledge of the current password (3.5.4).
use Mainul\PasswordPolicy\Rules\CurrentPasswordRule; $request->validate([ 'current_password' => ['required', new CurrentPasswordRule($user)], ]);
The rule is skipped for system-forced changes: when the user has a temporary password
(current_password.skip_when_forced) or the password has expired (skip_when_expired). For an administrator
resetting someone else's password, simply do not apply the rule. In such a form, drop required for
current_password when the user is forced to change, as the API does:
$rule = new CurrentPasswordRule($user); $needsCurrent = ! $rule->passes('current_password', ''); // false when forced/expired $request->validate(['current_password' => $needsCurrent ? ['required', $rule] : []]);
4. Password expiry
// config/password-policy.php 'expiry' => [ 'enabled' => true, 'days' => 30, // maximum password age 'grace_days' => 1, // disable the account this many days after expiry 'auto_disable' => true, // schedule the daily sweep + disable on the spot in middleware ],
Prompt users — add password.expiry to authenticated routes. Web requests are redirected to
middleware.password_change_route (password.change) with a warning; JSON requests get
403 {"error": "password_expired"}.
Disable overdue accounts — one day after expiry (configurable). Runs daily through the scheduler, on demand with the command, or from code:
php artisan password-policy:disable-expired --dry-run # list what would be disabled
php artisan password-policy:disable-expired
use Mainul\PasswordPolicy\Services\ExpiredAccountSweeper; use Mainul\PasswordPolicy\Services\PasswordExpiryService; app(PasswordExpiryService::class)->isExpired($user); // password older than allowed? app(PasswordExpiryService::class)->isDisableDue($user); // past expiry + grace? app(ExpiredAccountSweeper::class)->sweep(dryRun: true); // count of accounts affected
Service accounts follow a rotation schedule instead of expiry (see 13).
5. Temporary passwords
Used when an administrator creates an account or resets a password for someone. The password is random, never returned, delivered only by an approved channel, and must be changed at first login.
use Mainul\PasswordPolicy\Services\TemporaryPasswordService; use Mainul\PasswordPolicy\Exceptions\{NoSecureChannelException, DeliveryFailedException}; try { $channel = app(TemporaryPasswordService::class)->issueFor($user); // "mail" or "sms" } catch (NoSecureChannelException $e) { // user has neither a company email nor a registered phone — nothing was changed } catch (DeliveryFailedException $e) { // send failed — the password change was rolled back }
Bundled web route (off by default, the web twin of POST api/password-policy/admin/users/{user}/temporary-password):
set admin_routes.enabled => true and POST admin/users/{user}/temporary-password (route name
password-policy.admin.users.temporary-password) is registered, together with the other admin actions (see
Web admin routes). It reissues through issueFor() and never shows the password.
Web admin routes
admin_routes.enabled => true registers browser versions of the API's admin actions (change admin_routes.prefix /
admin_routes.middleware as needed). All need the api.abilities.users Gate ability (password-policy.manage-users),
are audited by their services, redirect back with a status flash (or errors on failure), and return the API's JSON
for Accept: application/json requests.
Route (under admin_routes.prefix) |
Name (password-policy.admin.) |
Does |
|---|---|---|
POST users/{user}/lock (reason) |
users.lock |
Lock now |
POST users/{user}/unlock (verified_by) |
users.unlock |
Unlock, recording who verified the user |
POST users/{user}/disable (reason) |
users.disable |
Disable the account |
POST users/{user}/enable |
users.enable |
Enable; password change forced at next login |
POST users/{user}/compromise |
users.compromise |
Password unusable, sessions ended |
POST users/{user}/temporary-password |
users.temporary-password |
Send a new temporary password |
POST users/{user}/terminate-sessions |
users.terminate-sessions |
End all sessions and tokens |
POST users/{user}/offboard |
users.offboard |
Leaver flow; flashes password_policy.rotation_required |
DELETE users/{user}/mfa |
users.mfa.reset |
Wipe the authenticator app |
POST accounts/disable-expired (dry_run) |
accounts.disable-expired |
Disable accounts expired past the grace period |
<form method="POST" action="{{ route('password-policy.admin.users.lock', $user) }}"> @csrf <input name="reason"> <button>Lock</button> </form> <form method="POST" action="{{ route('password-policy.admin.users.mfa.reset', $user) }}"> @csrf @method('DELETE') <button>Reset authenticator</button> </form>
The read-only API endpoints (show, known-logins), service accounts, settings, audit and compliance are not bundled
on the web because they need views; use the services directly.
- Channel order:
temporary_password.delivery_order(['mail', 'sms']). Company email first; SMS only when there is no usable email (3.1.3). There is never an unprotected fallback. - Company email only:
temporary_password.company_email_domains = ['acme.com']. - Policy-compliant: generated passwords satisfy your rules, skip look-alike characters (
0 O 1 l I) and avoid anything resembling the user's personal data. - Forced change:
issueFor()setsmust_change_password; thepassword.force_changemiddleware then blocks every route except those inmiddleware.excluded_routes. - SMS needs
composer require xenon/laravelbdsmsand aphonecolumn (columns.phone).
Automatic on user creation (off by default): set temporary_password.auto_issue_on_create => true and every
user created through a model using HasPasswordPolicy gets a temporary password issued and delivered right after
the insert, replacing whatever password was passed to create() (supply any placeholder if the column is required).
A missing channel or failed delivery never blocks the creation: the error is reported and audited, and you can
re-issue later with issueFor(). To skip some users (e.g. self-registration), override on the model:
public function shouldIssueTemporaryPassword(): bool { return ! $this->self_registered; }
Add your own channel (e.g. WhatsApp, Slack DM):
use Illuminate\Contracts\Auth\Authenticatable; use Mainul\PasswordPolicy\Contracts\PasswordDeliveryChannel; use Mainul\PasswordPolicy\Exceptions\DeliveryFailedException; class WhatsAppChannel implements PasswordDeliveryChannel { public function name(): string { return 'whatsapp'; } public function canDeliverTo(Authenticatable $user): bool { return filled($user->whatsapp_number); } public function send(Authenticatable $user, string $temporaryPassword): void { $this->sendText($user, "Your temporary password: {$temporaryPassword}", 'Temporary password'); } public function sendText(Authenticatable $user, string $text, ?string $subject = null): void { // call your gateway; throw DeliveryFailedException on failure; NEVER log $text } } // config/password-policy.php 'temporary_password' => [ 'delivery_order' => ['mail', 'whatsapp', 'sms'], 'channels' => [ 'mail' => \Mainul\PasswordPolicy\Delivery\MailChannel::class, 'sms' => \Mainul\PasswordPolicy\Delivery\SmsChannel::class, 'whatsapp' => \App\Security\WhatsAppChannel::class, ], ],
Generate only (no delivery), e.g. for tests or seeding:
$plain = app(TemporaryPasswordService::class)->generate(length: 16, forUser: $user); $user->setTemporaryPassword(Hash::make($plain))->save();
6. Account lockout
Tiered lockout after repeated failures (3.4.1, 3.4.2):
'lockout' => [ 'enabled' => true, 'max_attempts' => 5, // consecutive failures per cycle 'durations' => [5, 10, 30],// minutes for the 1st, 2nd, 3rd lock 'extended_minutes' => 120, // every later lock — also needs identity verification to unlock 'reset_after_hours' => 24, 'ip_burst' => ['enabled' => true, 'attempts' => 5, 'window_seconds' => 60], ],
An IP burst (5 failures from one IP against one account in 60 s) locks the account permanently until an administrator unlocks it.
Block sign-ins with LoginGuard (see Quick start). It also disables accounts that are past
expiry. The exception exposes details for your UI:
catch (AccountLockedException $e) { $e->retryAfterSeconds; // ?int — null for permanent/verification locks $e->reason; // 'disabled' | 'temporary' | 'permanent' | 'verification' // (show users the generic message; keep the reason for your own logs) }
Manage locks from code (administrator actions are audited):
use Mainul\PasswordPolicy\Services\LockoutService; $lockout = app(LockoutService::class); $lockout->lockState($user); // ['type' => 'temporary|verification|permanent', 'until' => Carbon|null] or null $lockout->isLocked($user); // bool $lockout->lock($user, $admin, 'Suspicious activity'); // permanent administrator lock $lockout->unlock($user, verifiedBy: $admin); // $verifiedBy is required for permanent/verification locks
From the CLI there is no unlock command; use the API (POST admin/users/{id}/unlock) or the service above.
Listen for AccountLocked to notify the user or SOC (see Events).
7. Disable, enable and compromise accounts
use Mainul\PasswordPolicy\Services\AccountService; $accounts = app(AccountService::class); $accounts->disable($user, 'Left the company', actor: $admin); // blocks sign-in, ends sessions $accounts->enable($user, actor: $admin); // re-enables and forces a password change $accounts->markCompromised($user, actor: $admin); // 3.7.5: password made unusable, // every session/token ended, change forced $accounts->isDisabled($user);
markCompromised() dispatches the PasswordCompromised event. Follow it with
TemporaryPasswordService::issueFor($user) once identity is verified.
8. Session termination
On a password change the trait ends the user's other sessions and API tokens, so the old password stops
working everywhere (3.5.2). The session/token that made the change stays signed in. Disable with
sessions.terminate_on_password_change = false.
use Mainul\PasswordPolicy\Services\SessionTerminator; app(SessionTerminator::class)->terminate($user); // everything app(SessionTerminator::class)->terminate($user, keepCurrent: true, reason: 'manual'); // keep this session
It bumps the user's session_version (enforced by password.session_version), clears database sessions and
deletes Sanctum/Passport tokens.
9. Password reset protection
Restrict roles that may not self-reset (3.6.6).
'reset' => [ 'restricted_roles' => ['BA', 'SO'], // must contact an administrator 'role_attribute' => 'role', // string or array attribute on the user 'role_resolver' => \App\Security\RoleResolver::class, // optional, wins over role_attribute ],
// App\Security\RoleResolver — invokable, returns a role name or list of roles class RoleResolver { public function __invoke($user): array { return $user->roles()->pluck('name')->all(); } }
// Forgot-password route: Route::post('/forgot-password', [...])->middleware('password.block_self_reset'); // or as a validation rule: $request->validate(['email' => ['required', 'email', new \Mainul\PasswordPolicy\Rules\CanSelfResetPassword()]]);
Independent identity check (3.6.2). Send and verify a one-time code before accepting the new password — especially useful for phone-only users:
use Mainul\PasswordPolicy\Contracts\ResetIdentityVerifier; $verifier = app(ResetIdentityVerifier::class); // Step 1: user asks for a reset $channel = $verifier->issue($user); // code goes to company email, else phone // Step 2: user submits the code with the new password if (! $verifier->verify($user, $request->code)) { // single use, 10 min, locks after 5 wrong tries abort(422, 'Invalid or expired code.'); } $user->update(['password' => Hash::make($request->password)]); event(new \Illuminate\Auth\Events\PasswordReset($user)); // audit + "your password was reset" notice
Tune with reset.code_length (6), reset.code_ttl_minutes (10), reset.code_max_attempts (5). Replace the verifier by
setting reset.verifier to your class implementing ResetIdentityVerifier.
Reset notice (3.6.5). When reset.notify is true, Laravel's PasswordReset event sends the user a notice
(never containing a password). Link expiry — password-policy:check fails if a broker's expire exceeds
reset.max_expire_minutes (60).
10. Authenticator-app MFA (TOTP)
Optional second step: the user types the 6-digit code from Google/Microsoft Authenticator, Authy or similar. Off by default. Once enabled, it is required, and users without an app are sent to a set-up page.
php artisan migrate php artisan password-policy:totp --enable --scope=all --grace-days=7 php artisan password-policy:totp --status
Option A — bundled pages. In the config set totp.routes => true (adds mfa/enroll, mfa/challenge,
mfa/recovery-codes; route names mfa.enroll, mfa.enroll.confirm, mfa.challenge, mfa.verify,
mfa.recovery). Then add the middleware:
Route::middleware(['auth', 'password.mfa'])->group(function () { /* protected routes */ });
After a password login password.mfa redirects to the set-up page (no app yet) or the code page (app set up,
code not yet entered). Restyle with vendor:publish --tag=password-policy-views.
Option B — build your own UI on TotpEnrollmentService:
use Mainul\PasswordPolicy\Services\{TotpEnrollmentService, MfaService}; $totp = app(TotpEnrollmentService::class); // Enrolment $data = $totp->begin($user); // ['secret' => 'JBSWY3DP...', 'uri' => 'otpauth://totp/...'] // render $data['uri'] as a QR code (or show $data['secret']) $recovery = $totp->confirm($user, $request->code); // array of recovery codes (shown ONCE) or null if the code is wrong // Sign-in challenge $mfa = app(MfaService::class); if ($mfa->isRequired($user, $request) && ! $mfa->isVerified($user, $request)) { if ($mfa->verify($user, $request->code, $request)) { // accepts a TOTP code or a recovery code return redirect()->intended(); } // wrong code — counts toward the account lockout } // Management $totp->recoveryCodesRemaining($user); $totp->regenerateRecoveryCodes($user); $totp->reset($user, actor: $admin); // lost phone: user re-enrols at next login
Config or database? totp.* in config/password-policy.php are defaults. The password_policy_settings table
overrides totp.enabled, totp.scope, totp.grace_days and totp.issuer (the database wins) — change them with
password-policy:totp or PUT admin/settings so the change is audited. To pin the policy in code set
totp.enabled = true and totp.lock_to_config = true.
use Mainul\PasswordPolicy\Services\SettingsRepository; $settings = app(SettingsRepository::class); $settings->get('totp.scope'); // effective value (db wins over config) $settings->set('totp.scope', 'admins', $admin); $settings->forget('totp.scope', $admin); // back to the config default
| Option | Meaning |
|---|---|
totp.scope |
all, admins, or remote (outside mfa.internal_networks). Admins always need MFA. |
totp.grace_days |
Days after --enable that unenrolled users can still sign in. Enrolled users are always challenged. Enabling through config alone gives no grace period. |
totp.issuer |
Name shown in the app (defaults to app name). |
totp.window |
Clock drift accepted either side (1 = ±30 s). |
totp.recovery_codes |
How many backup codes (default 8). |
mfa.internal_networks |
CIDR list of trusted networks, e.g. ['10.0.0.0/8', '192.168.1.0/24']. |
mfa.require_all |
Require MFA for every user. |
Security notes. The secret is stored encrypted with APP_KEY (changing the key makes secrets unreadable,
so users would need a reset). Recovery codes are keyed hashes shown once. A code can be used once (replay
blocked), wrong codes count toward lockout, the session id is renewed on success, and an enrolled app can not be
replaced from a password-only session. If the settings table is unreachable, config defaults are used.
11. Custom MFA driver
Prefer SMS, e-mail OTP or push? Implement MfaDriver and point mfa.driver at it. A driver you configure takes
priority over the built-in one.
use Illuminate\Contracts\Auth\Authenticatable; use Mainul\PasswordPolicy\Contracts\MfaDriver; class SmsCodeDriver implements MfaDriver { public function isEnrolled(Authenticatable $user): bool { return filled($user->phone); } public function challenge(Authenticatable $user): void // send the code { $code = random_int(100000, 999999); Cache::put("sms-mfa:{$user->id}", Hash::make((string) $code), now()->addMinutes(5)); Sms::to($user->phone)->send("Your login code: {$code}"); } public function verify(Authenticatable $user, string $code): bool { $hash = Cache::pull("sms-mfa:{$user->id}"); // pull = single use return $hash && Hash::check($code, $hash); } } // config/password-policy.php 'mfa' => [ 'driver' => \App\Security\SmsCodeDriver::class, 'require_remote' => true, 'internal_networks' => ['10.0.0.0/8'], 'require_all' => false, 'token_ttl_minutes' => 720, // API tokens: how long a passed MFA stays valid ],
Who needs MFA: admins always; plus remote users (require_remote with a non-empty internal_networks) and
everyone if require_all is true. With no factor available, users who need MFA are blocked (fail closed).
Enrolment endpoints answer 404 mfa_external_driver with a host driver because set-up is your driver's job.
12. Admin accounts
Admins (a role in admin.roles or a truthy admin.flag_attribute) get stricter rules; the stricter of the global
and admin value applies.
'admin' => [ 'roles' => ['ADMIN', 'SUPER_ADMIN', 'SUPERADMIN'], 'flag_attribute' => 'is_admin', 'rules' => ['min_length' => 14], // any key from `rules` can be overridden 'expiry_days' => 60, 'history_count' => 5, 'daily_email_domains' => ['gmail.com', 'acme.com'], // admins logging in with these are flagged ],
PasswordPolicyRule::for($admin); // 14+ characters app(\Mainul\PasswordPolicy\Services\AccountClassifier::class)->isAdmin($user); app(\Mainul\PasswordPolicy\Services\PolicyProfile::class)->expiryDays($user);
password-policy:check flags admins whose login email is on a daily-use domain (3.9.1).
13. Service accounts and rotation
Service accounts (bots, integrations) need a named owner and purpose, rotate on a schedule instead of expiring, and never sign in interactively.
use Mainul\PasswordPolicy\Services\ServiceAccountService; $svc = app(ServiceAccountService::class); $svc->register($botUser, owner: 'Jane Doe', purpose: 'Nightly ETL', rotationDays: 90, knownBy: [12, 15]); $svc->update($botUser, ['owner' => 'John Roe', 'rotation_days' => 60]); $svc->due(); // Collection of accounts whose rotation is overdue $svc->notifyDue(); // emails owners + service_accounts.notify_recipients; returns count $svc->rotate($botUser); // new random secret -> vault; rolled back if the vault fails $svc->remove($botUser); // stop treating the user as a service account
knownBy lists the ids of people who know the password; offboarding one of them marks the account due.
Vault callback. The package never keeps or returns the secret; rotation is refused without a vault.
// config/password-policy.php 'service_accounts' => [ 'default_rotation_days' => 90, 'password_length' => 32, 'vault' => \App\Security\VaultWriter::class, 'notify_recipients' => ['security@acme.com'], ], // App\Security\VaultWriter — invokable class VaultWriter { public function __invoke(Authenticatable $user, string $secret): void { Vault::put("service-accounts/{$user->id}", ['password' => $secret]); // throw to abort + roll back } }
php artisan password-policy:rotation-due # list overdue php artisan password-policy:rotation-due --notify # email owners php artisan password-policy:rotation-due --rotate # rotate through the vault
14. Offboarding leavers
Disables the account the same day, ends every session/token and flags service-account passwords the person knew:
php artisan password-policy:offboard jane@acme.com --actor=admin@acme.com
use Mainul\PasswordPolicy\Services\OffboardingService; $mustRotate = app(OffboardingService::class)->offboard($user, actor: $admin); // Collection<ServiceAccount> — their next_rotation_at is now, so `rotation-due` picks them up foreach ($mustRotate as $account) { app(ServiceAccountService::class)->rotate($account->user); }
15. Audit log
Logins, failures, lockouts, password changes, resets, MFA, admin actions, etc. are written to
password_audit_logs without secrets (keys in audit.redact_keys are redacted, e.g. password, token,
code, otp).
// Reading is denied until YOU define the ability (3.7.3): Gate::define('view-password-audit-logs', fn ($user) => in_array($user->role, ['SECURITY', 'AUDITOR'])); // Query it use Mainul\PasswordPolicy\Models\PasswordAuditLog; PasswordAuditLog::where('user_id', $id)->where('outcome', 'failure')->latest()->take(50)->get(); // Write your own entry use Mainul\PasswordPolicy\Services\AuditLogger; app(AuditLogger::class)->log('report_exported', AuditLogger::OUTCOME_SUCCESS, $user, null, ['rows' => 120]); // outcomes: success | failure | blocked | alert
php artisan password-policy:audit --user=jane@acme.com --event=login --outcome=failure --limit=50
Keep secrets out of application logs (3.7.2) — add the tap to a channel in config/logging.php:
'single' => [ 'driver' => 'single', 'path' => storage_path('logs/laravel.log'), 'tap' => [\Mainul\PasswordPolicy\Logging\RedactSensitiveData::class], ],
Also available: Mainul\PasswordPolicy\Support\Redactor::redact($array).
16. Unusual-login detection
Alerts when an account collects anomaly.failure_threshold failures within anomaly.window_minutes, or when a
successful login comes from a new network (IPv4 /24, IPv6 /48 by default) or, with a resolver, a new
country. The first login only sets the baseline. Each alert is audited, emailed to anomaly.alert_recipients
and dispatched as UnusualLoginDetected.
// Optional country check — implement the contract with any GeoIP library use Mainul\PasswordPolicy\Contracts\GeoResolver; class MaxMindGeo implements GeoResolver { public function country(string $ip): ?string { return GeoIP::getLocation($ip)->iso_code ?? null; // two-letter code or null } } // config 'anomaly' => [ 'enabled' => true, 'failure_threshold' => 3, 'window_minutes' => 10, 'geo_resolver' => \App\Security\MaxMindGeo::class, 'alert_recipients' => ['soc@acme.com'], ],
No external geo service is bundled.
17. Secure transport (HTTPS)
password.secure rejects non-HTTPS requests (3.3.1) and requests carrying secrets in the query string (3.3.2).
It is active only when APP_ENV=production unless forced:
'tls' => [ 'enforce' => null, // null = production only, true = always, false = never 'forbidden_query_keys' => ['password', 'current_password', 'pwd', /* ... */], ],
Route::post('/login', ...)->middleware('password.secure');
Behind a proxy/load balancer, configure Laravel's trusted proxies so $request->secure() is correct.
18. Default-password scan
Before go-live, find accounts still using a known default password (3.9.5). Add your vendor defaults to
defaults.passwords.
php artisan password-policy:check-defaults # report php artisan password-policy:check-defaults --flag # also force those users to change php artisan password-policy:check-defaults --user=42 # one user
$result = app(\Mainul\PasswordPolicy\Services\DefaultPasswordScanner::class)->scan(flag: true);
It hashes each candidate per user, so it is slow on large tables: run it off-peak.
JSON API
Everything above is also available over HTTP, for mobile apps, SPAs and other services. It is off by default:
the routes exist but answer 404 until enabled, either in the config or at runtime without a deploy:
// config/password-policy.php 'api' => ['enabled' => true], // or at runtime app(\Mainul\PasswordPolicy\Services\SettingsRepository::class)->set('api.enabled', true);
Authentication. The guard is sanctum by default (composer require laravel/sanctum). For Passport, set
api.guard to the guard whose driver is passport (usually api); a list such as ['sanctum', 'api'] tries each
in turn. It can be set in the config or in the database (api.guard); the database wins and is read on every request.
Authorization. /admin endpoints are checked against Gate abilities that deny everyone until you define
them:
Gate::define('password-policy.manage-users', fn ($user) => $user->isSecurityOfficer()); Gate::define('password-policy.manage-service-accounts', fn ($user) => $user->isSecurityOfficer()); Gate::define('password-policy.manage-settings', fn ($user) => $user->isSecurityOfficer()); Gate::define('password-policy.view-compliance', fn ($user) => $user->isSecurityOfficer()); Gate::define('view-password-audit-logs', fn ($user) => $user->isSecurityOfficer());
By default /admin also sits behind password.expiry, password.force_change and password.mfa
(api.admin_requires_mfa, read when routes load), so admins need an enrolled authenticator first.
Paths are relative to api.prefix (default /api/password-policy). Errors are JSON:
{"message": "...", "error": "code"}, or Laravel's {"errors": {...}} for validation. Throttling:
api.throttle.public (6,1) for anonymous endpoints, api.throttle.sensitive (10,1) for secret-checking ones.
Endpoints
| Method and path | Who | Purpose |
|---|---|---|
POST login/check |
anyone, throttled | Is this account allowed to try a password? 423 if locked or disabled. Call before checking credentials. |
POST reset/code |
anyone, throttled | Send a one-time code to the user's company email or phone. Always 202. |
POST reset/password |
anyone, throttled | email, code, password, password_confirmation. Checks the code, applies the policy, sets the password. |
GET policy |
signed in | The rules that apply to the caller (admins get stricter ones). |
GET password/status |
signed in | Expiry date, days left, forced-change flag, MFA state. |
POST password/validate |
signed in | Check a candidate password; changes nothing. |
PUT password |
signed in | current_password, password, password_confirmation. Ends the user's other sessions and tokens. |
GET mfa/status |
signed in | Whether MFA is on, required, enrolled, and verified for this token. |
POST mfa/enroll |
signed in | Start set-up: returns the key, the otpauth:// URI and (with bacon/bacon-qr-code) an SVG. |
POST mfa/enroll/confirm |
signed in | code from the app. Returns recovery codes once. |
POST mfa/challenge |
signed in | Start a challenge for drivers that need one (send an SMS code). |
POST mfa/verify |
signed in | code (or a recovery code). Marks this token as MFA-verified. |
POST mfa/recovery-codes |
signed in | password. New recovery codes; needs a verified token. Built-in app only. |
GET admin/users/{id} |
users | Security state of an account. |
GET admin/users/{id}/known-logins |
users | Networks/countries the user signed in from. |
POST admin/users/{id}/lock |
users | reason optional. Permanent lock. |
POST admin/users/{id}/unlock |
users | verified_by required for permanent and identity-verification locks. |
POST admin/users/{id}/disable, .../enable |
users | reason optional. Enabling forces a password change. |
POST admin/users/{id}/compromise |
users | Make the password unusable and end every session (3.7.5). |
POST admin/users/{id}/temporary-password |
users | Send a new temporary password to the approved channel (never returned). |
POST admin/users/{id}/terminate-sessions |
users | End all sessions and API tokens. |
POST admin/users/{id}/offboard |
users | Disable a leaver and list the shared passwords to rotate. |
DELETE admin/users/{id}/mfa |
users | Wipe a user's authenticator app (lost device). |
POST admin/accounts/disable-expired |
users | dry_run optional. Disable accounts past expiry plus grace. |
GET admin/service-accounts[?due=1] |
service accounts | List. |
POST admin/service-accounts |
service accounts | user_id, owner, purpose, rotation_days, known_by[]. |
PUT, DELETE admin/service-accounts/{id} |
service accounts | Update, or stop treating the user as a service account. |
POST admin/service-accounts/{id}/rotate, .../rotate-due |
service accounts | Rotate through your vault. |
POST admin/service-accounts/notify-due |
service accounts | Email owners about overdue rotations. |
GET, PUT admin/settings, DELETE admin/settings/{key} |
settings | Database overrides: totp.*, api.enabled, api.guard. |
GET admin/audit |
audit gate | Filters: user_id, event, outcome, from, to, per_page. |
GET admin/compliance |
compliance | The password-policy:check self-test. |
POST admin/compliance/default-passwords, GET .../{scan_id} |
users | Default-password scan (queued unless user_id is given). |
Examples
Mobile login flow (your login endpoint issues the Sanctum token):
# 1. May this account try a password? curl -X POST https://app.test/api/password-policy/login/check \ -H 'Accept: application/json' -d 'email=jane@acme.com' # 200 {"allowed": true} # 423 {"message": "This account is currently unavailable...", "error": "account_unavailable", "retry_after": 300} # 2. After your own login returns a token, check the password state curl https://app.test/api/password-policy/password/status \ -H 'Accept: application/json' -H "Authorization: Bearer $TOKEN" # {"data": {"expired": false, "days_remaining": 12, "must_change_password": false, # "mfa": {"required": true, "enrolled": true, "verified": false}}}
Change password:
curl -X PUT https://app.test/api/password-policy/password \ -H 'Accept: application/json' -H "Authorization: Bearer $TOKEN" \ -d 'current_password=Old#Passw0rd1' -d 'password=N3w#Secret-Pass' -d 'password_confirmation=N3w#Secret-Pass' # 200 {"message": "Password changed."} # 422 {"errors": {"password": ["The password must contain ..."]}}
current_password may be omitted when the password is temporary or expired.
Pre-validate while the user types (changes nothing):
curl -X POST .../password/validate -H "Authorization: Bearer $TOKEN" -d 'password=abc' # {"valid": false, "errors": ["The password must contain at least 11 characters, ..."]}
Forgotten password (not signed in):
curl -X POST .../reset/code -d 'email=jane@acme.com' # always 202 curl -X POST .../reset/password -d 'email=jane@acme.com' -d 'code=482913' \ -d 'password=N3w#Secret-Pass' -d 'password_confirmation=N3w#Secret-Pass'
Authenticator app from a mobile client:
curl -X POST .../mfa/enroll -H "Authorization: Bearer $TOKEN" # {"data": {"secret": "JBSW...", "uri": "otpauth://totp/...", "qr_svg": "<svg ...>"}} curl -X POST .../mfa/enroll/confirm -H "Authorization: Bearer $TOKEN" -d 'code=123456' # {"data": {"recovery_codes": ["ABCD-EFGH", ...]}} <- shown once curl -X POST .../mfa/verify -H "Authorization: Bearer $TOKEN" -d 'code=654321'
Admin: unlock an account, switch the API guard:
curl -X POST .../admin/users/42/unlock -H "Authorization: Bearer $ADMIN_TOKEN" -d 'verified_by=helpdesk-17' curl -X PUT .../admin/settings -H "Authorization: Bearer $ADMIN_TOKEN" \ -H 'Content-Type: application/json' -d '{"settings": {"api.guard": "api", "totp.scope": "admins"}}'
Notes
- MFA for tokens. There is no session, so a passed code is remembered per bearer token in the cache for
mfa.token_ttl_minutes(12 h). Use a shared cache store on more than one server. Cookie-based SPA requests use the session. - Reset codes.
reset/passwordspends the code before the checks that need the user (reuse, personal info), so they cannot be used to probe accounts. If one fails, request a new code. - Not part of the API: the login action itself (use
login/checkbefore yours) and the Laravel reset-link flow (the API's own reset applies the same restricted-role rule).
Complete example (fresh Laravel project, MVC)
A copy-and-paste walkthrough that uses every feature in a brand-new Laravel 11/12/13 app with no starter kit.
It follows MVC: Models (User), Views (Blade), Controllers (thin) and Form Requests. Business logic
stays in the package services. File paths are relative to the project root. Do the steps in order.
Step 1. Create the project and install
composer create-project laravel/laravel acme-portal
cd acme-portal
composer require mainul/password-policy laravel/sanctum bacon/bacon-qr-code
php artisan vendor:publish --tag=password-policy-config
Set the database and mail in .env, then use a shared cache store if you run more than one server:
DB_CONNECTION=mysql DB_DATABASE=acme_portal MAIL_MAILER=log # use smtp in production; temporary passwords are delivered by mail SESSION_DRIVER=database # lets the package end a user's other sessions CACHE_STORE=database # shared store for lockout/MFA counters (Redis on a cluster)
Step 2. Migrations
The package migrations are loaded automatically. Add your own columns the package reads (role, phone,
date_of_birth). Give the file a name that sorts after Laravel's create_users_table:
php artisan make:migration add_profile_columns_to_users_table --table=users
// database/migrations/xxxx_add_profile_columns_to_users_table.php public function up(): void { Schema::table('users', function (Blueprint $table) { $table->string('role')->default('USER')->after('email'); // USER, ADMIN, BA, SO, SECURITY $table->string('phone')->nullable()->after('role'); // SMS fallback for temporary passwords $table->date('date_of_birth')->nullable()->after('phone'); // personal-info check }); }
php artisan migrate
Step 3. Configuration
Edit config/password-policy.php (only the keys below differ from the defaults):
'admin' => ['roles' => ['ADMIN'], 'flag_attribute' => null], 'reset' => ['restricted_roles' => ['BA', 'SO'], 'role_attribute' => 'role'], 'totp' => ['routes' => true, 'enabled' => false], // flip on later with the command in Step 11 'api' => ['enabled' => true, 'guard' => 'sanctum'], 'anomaly' => ['alert_recipients' => ['security@acme.com']], 'service_accounts' => [ 'vault' => \App\Security\VaultWriter::class, 'notify_recipients' => ['security@acme.com'], ], 'temporary_password' => ['company_email_domains' => ['acme.com']],
totp.routes => true registers mfa/enroll, mfa/challenge and mfa/recovery-codes with ready-made pages, so
you do not write MFA controllers or views. Laravel 11+ also needs API routes installed for the JSON API:
php artisan install:api.
Step 4. Model: app/Models/User.php
<?php namespace App\Models; use Illuminate\Database\Eloquent\Factories\HasFactory; use Illuminate\Foundation\Auth\User as Authenticatable; use Illuminate\Notifications\Notifiable; use Laravel\Sanctum\HasApiTokens; use Mainul\PasswordPolicy\Traits\HasPasswordPolicy; class User extends Authenticatable { use HasApiTokens, HasFactory, Notifiable, HasPasswordPolicy; protected $fillable = ['name', 'email', 'password', 'role', 'phone', 'date_of_birth']; protected $hidden = ['password', 'remember_token']; protected function casts(): array { return ['email_verified_at' => 'datetime', 'password' => 'hashed', 'date_of_birth' => 'date']; } public function isSecurityOfficer(): bool { return in_array($this->role, ['SECURITY', 'ADMIN'], true); } // Self-registered users choose their own password: no temporary password for them. public function shouldIssueTemporaryPassword(): bool { return false; } }
On Laravel 10 remove the
casts()method, useprotected $casts = [...]and keepHash::make()in the controllers below. On 11+Hash::make()is still safe: thehashedcast never double-hashes.
Step 5. Routes: routes/web.php
<?php use App\Http\Controllers\Admin\AuditLogController; use App\Http\Controllers\Admin\UserController as AdminUserController; use App\Http\Controllers\Auth\ForgotPasswordController; use App\Http\Controllers\Auth\LoginController; use App\Http\Controllers\Auth\PasswordController; use App\Http\Controllers\Auth\RegisterController; use App\Http\Controllers\DashboardController; use Illuminate\Support\Facades\Route; Route::redirect('/', '/login'); // Public: HTTPS-only, no secrets in the URL (3.3) Route::middleware(['guest', 'password.secure'])->group(function () { Route::get('/login', [LoginController::class, 'create'])->name('login'); Route::post('/login', [LoginController::class, 'store']); Route::get('/register', [RegisterController::class, 'create'])->name('register'); Route::post('/register', [RegisterController::class, 'store']); // Restricted roles (BA, SO) are blocked from self-service reset (3.6.6) Route::get('/forgot-password', [ForgotPasswordController::class, 'create'])->name('password.request'); Route::post('/forgot-password', [ForgotPasswordController::class, 'store']) ->middleware('password.block_self_reset')->name('password.email'); Route::post('/reset-password', [ForgotPasswordController::class, 'update'])->name('password.reset.store'); }); // Signed in, but must stay reachable even when the password is expired/temporary Route::middleware(['auth', 'password.secure'])->group(function () { Route::post('/logout', [LoginController::class, 'destroy'])->name('logout'); Route::get('/password/change', [PasswordController::class, 'edit'])->name('password.change'); Route::put('/password', [PasswordController::class, 'update'])->name('password.update'); }); // Everything else: full policy stack, in this order Route::middleware(['auth', 'password.account_active', 'password.session_version', 'password.expiry', 'password.force_change', 'password.mfa'])->group(function () { Route::get('/dashboard', DashboardController::class)->name('dashboard'); Route::prefix('admin')->name('admin.')->middleware('can:password-policy.manage-users')->group(function () { Route::get('users', [AdminUserController::class, 'index'])->name('users.index'); Route::post('users', [AdminUserController::class, 'store'])->name('users.store'); Route::post('users/{user}/temporary-password', [AdminUserController::class, 'temporaryPassword'])->name('users.temp'); Route::post('users/{user}/lock', [AdminUserController::class, 'lock'])->name('users.lock'); Route::post('users/{user}/unlock', [AdminUserController::class, 'unlock'])->name('users.unlock'); Route::post('users/{user}/disable', [AdminUserController::class, 'disable'])->name('users.disable'); Route::post('users/{user}/enable', [AdminUserController::class, 'enable'])->name('users.enable'); Route::post('users/{user}/compromised', [AdminUserController::class, 'compromised'])->name('users.compromised'); Route::post('users/{user}/offboard', [AdminUserController::class, 'offboard'])->name('users.offboard'); }); Route::get('admin/audit', AuditLogController::class)->middleware('can:view-password-audit-logs')->name('admin.audit'); });
The route names password.change, password.update and logout match the package's default
middleware.excluded_routes, so the expiry and forced-change checks do not trap the user in a redirect loop.
Step 6. Controllers
Login (account lockout, disabled/expired accounts, generic message): app/Http/Controllers/Auth/LoginController.php
<?php namespace App\Http\Controllers\Auth; use App\Http\Controllers\Controller; use Illuminate\Http\Request; use Illuminate\Support\Facades\Auth; use Mainul\PasswordPolicy\Exceptions\AccountLockedException; use Mainul\PasswordPolicy\Services\LoginGuard; class LoginController extends Controller { public function create() { return view('auth.login'); } public function store(Request $request, LoginGuard $guard) { $credentials = $request->validate(['email' => ['required', 'email'], 'password' => ['required']]); try { $guard->ensureCanAttempt($credentials['email']); // BEFORE checking the password } catch (AccountLockedException $e) { // Same message for locked, disabled and expired accounts. $e->reason stays server-side. return back()->withErrors(['email' => $e->getMessage()])->onlyInput('email'); } if (! Auth::attempt($credentials, $request->boolean('remember'))) { // The package's Failed listener counts this toward lockout and the audit log. return back()->withErrors(['email' => 'These credentials do not match our records.'])->onlyInput('email'); } $request->session()->regenerate(); // password.force_change / password.expiry / password.mfa take over from here. return redirect()->intended(route('dashboard')); } public function destroy(Request $request) { Auth::logout(); $request->session()->invalidate(); $request->session()->regenerateToken(); return redirect('/login'); } }
Registration (no user yet, so the string alias password_policy is used): app/Http/Controllers/Auth/RegisterController.php
<?php namespace App\Http\Controllers\Auth; use App\Http\Controllers\Controller; use App\Models\User; use Illuminate\Http\Request; use Illuminate\Support\Facades\Auth; use Illuminate\Support\Facades\Hash; use Mainul\PasswordPolicy\Rules\PasswordPolicyRule; class RegisterController extends Controller { public function create() { return view('auth.register'); } public function store(Request $request) { $data = $request->validate([ 'name' => ['required', 'string', 'max:255'], 'email' => ['required', 'email', 'unique:users'], 'date_of_birth' => ['nullable', 'date'], 'password' => ['required', 'confirmed', 'password_policy'], ]); $user = User::create([...$data, 'password' => Hash::make($data['password'])]); // Re-check now that a user exists: this adds the personal-information test (name, email, birthdate). if (! (new PasswordPolicyRule($user))->passes('password', $data['password'])) { $user->delete(); return back()->withErrors(['password' => 'The password must not contain your personal information.']) ->onlyInput('name', 'email'); } Auth::login($user); return redirect()->route('dashboard'); } }
Change password (current password, rules, no reuse, history, session termination): app/Http/Controllers/Auth/PasswordController.php
<?php namespace App\Http\Controllers\Auth; use App\Http\Controllers\Controller; use Illuminate\Http\Request; use Illuminate\Support\Facades\Hash; use Mainul\PasswordPolicy\Rules\{CurrentPasswordRule, PasswordNotReusedRule, PasswordPolicyRule}; class PasswordController extends Controller { public function edit(Request $request) { $user = $request->user(); return view('auth.change-password', [ 'forced' => $user->mustChangePassword(), 'expired' => $user->passwordExpired(), // The current password is not asked for system-forced changes (temporary/expired password). 'needCurrent' => ! $user->mustChangePassword() && ! $user->passwordExpired(), ]); } public function update(Request $request) { $user = $request->user(); $currentRule = new CurrentPasswordRule($user); $request->validate([ 'current_password' => $currentRule->passes('current_password', '') ? [] : ['required', $currentRule], 'password' => ['required', 'confirmed', PasswordPolicyRule::for($user), // admins get the stricter rules new PasswordNotReusedRule($user)], // last N passwords are rejected ]); // The trait saves history, stamps password_changed_at, clears must_change_password, // ends the OTHER sessions/tokens and writes the audit entry. $user->update(['password' => Hash::make($request->password)]); return redirect()->route('dashboard')->with('status', 'Password changed.'); } }
Forgot / reset password (Laravel's broker + restricted roles + independent one-time code): app/Http/Controllers/Auth/ForgotPasswordController.php
<?php namespace App\Http\Controllers\Auth; use App\Http\Controllers\Controller; use App\Models\User; use Illuminate\Auth\Events\PasswordReset; use Illuminate\Http\Request; use Illuminate\Support\Facades\Hash; use Illuminate\Support\Facades\Password; use Mainul\PasswordPolicy\Contracts\ResetIdentityVerifier; use Mainul\PasswordPolicy\Rules\{PasswordNotReusedRule, PasswordPolicyRule}; class ForgotPasswordController extends Controller { public function create() { return view('auth.forgot-password'); } // Step 1: BA/SO never reach this method (password.block_self_reset on the route). public function store(Request $request, ResetIdentityVerifier $verifier) { $request->validate(['email' => ['required', 'email']]); Password::sendResetLink($request->only('email')); // link expires per config/auth.php (<= 60 min) if ($user = User::where('email', $request->email)->first()) { $verifier->issue($user); // one-time code to company email, else phone } // Identical answer for known and unknown emails. return back()->with('status', 'If the account exists, a reset link and a verification code were sent.'); } // Step 2: link token + one-time code + new password public function update(Request $request, ResetIdentityVerifier $verifier) { $user = User::where('email', $request->email)->first(); $request->validate([ 'token' => ['required'], 'email' => ['required', 'email'], 'code' => ['required'], 'password' => ['required', 'confirmed', PasswordPolicyRule::for($user), new PasswordNotReusedRule($user)], ]); if (! $user || ! $verifier->verify($user, $request->code)) { // single use, 10 min, max 5 tries return back()->withErrors(['code' => 'Invalid or expired code.']); } $status = Password::reset( $request->only('email', 'password', 'password_confirmation', 'token'), function (User $u, string $password) { $u->update(['password' => Hash::make($password)]); event(new PasswordReset($u)); // audit entry + "your password was reset" notice } ); return $status === Password::PASSWORD_RESET ? redirect()->route('login')->with('status', 'Password reset.') : back()->withErrors(['email' => __($status)]); } }
Dashboard: app/Http/Controllers/DashboardController.php
<?php namespace App\Http\Controllers; use Illuminate\Http\Request; class DashboardController extends Controller { public function __invoke(Request $request) { return view('dashboard', ['user' => $request->user()]); } }
Admin users (temporary passwords, lock/unlock, disable/enable, compromise, offboarding): app/Http/Controllers/Admin/UserController.php
<?php namespace App\Http\Controllers\Admin; use App\Http\Controllers\Controller; use App\Models\User; use Illuminate\Http\Request; use Illuminate\Support\Facades\Hash; use Illuminate\Support\Str; use Mainul\PasswordPolicy\Exceptions\{DeliveryFailedException, NoSecureChannelException}; use Mainul\PasswordPolicy\Services\{AccountService, LockoutService, OffboardingService, ServiceAccountService, TemporaryPasswordService}; class UserController extends Controller { public function index(LockoutService $lockout) { $users = User::orderBy('name')->paginate(25); return view('admin.users', ['users' => $users, 'lockout' => $lockout]); } // Create a user with a random temporary password delivered by email (or SMS), never shown on screen (3.1.x). public function store(Request $request, TemporaryPasswordService $temporary) { $data = $request->validate([ 'name' => ['required', 'string', 'max:255'], 'email' => ['required', 'email', 'unique:users'], 'phone' => ['nullable', 'string', 'max:30'], 'role' => ['required', 'in:USER,ADMIN,BA,SO,SECURITY'], ]); // Placeholder only: issueFor() immediately replaces it with the real temporary password. $user = User::create([...$data, 'password' => Hash::make(Str::random(40))]); return $this->issue($temporary, $user, 'User created.'); } public function temporaryPassword(User $user, TemporaryPasswordService $temporary) { return $this->issue($temporary, $user, 'Temporary password sent.'); } public function lock(Request $request, User $user, LockoutService $lockout) { $lockout->lock($user, $request->user(), $request->input('reason', 'Suspicious activity')); return back()->with('status', 'Account locked.'); } public function unlock(Request $request, User $user, LockoutService $lockout) { $lockout->unlock($user, verifiedBy: $request->user()); // required for permanent/verification locks return back()->with('status', 'Account unlocked.'); } public function disable(Request $request, User $user, AccountService $accounts) { $accounts->disable($user, $request->input('reason', 'Disabled by administrator'), actor: $request->user()); return back()->with('status', 'Account disabled; sessions ended.'); } public function enable(Request $request, User $user, AccountService $accounts) { $accounts->enable($user, actor: $request->user()); // forces a password change at next login return back()->with('status', 'Account enabled.'); } // 3.7.5: password made unusable, every session/token ended, change forced. public function compromised(Request $request, User $user, AccountService $accounts) { $accounts->markCompromised($user, actor: $request->user()); return back()->with('status', 'Marked compromised. Issue a temporary password once identity is verified.'); } // 3.8.3-3.8.5: disable the leaver today and rotate every shared secret they knew. public function offboard(Request $request, User $user, OffboardingService $offboarding, ServiceAccountService $svc) { foreach ($offboarding->offboard($user, actor: $request->user()) as $account) { $svc->rotate($account->user); } return back()->with('status', 'User offboarded.'); } private function issue(TemporaryPasswordService $temporary, User $user, string $ok) { try { $channel = $temporary->issueFor($user); // "mail" or "sms" } catch (NoSecureChannelException) { return back()->withErrors(['email' => 'The user has no company email or registered phone.']); } catch (DeliveryFailedException) { return back()->withErrors(['email' => 'Delivery failed; nothing was changed.']); } return back()->with('status', "{$ok} Sent by {$channel}."); } }
Audit log viewer: app/Http/Controllers/Admin/AuditLogController.php
<?php namespace App\Http\Controllers\Admin; use App\Http\Controllers\Controller; use Illuminate\Http\Request; use Mainul\PasswordPolicy\Models\PasswordAuditLog; class AuditLogController extends Controller { public function __invoke(Request $request) { $logs = PasswordAuditLog::query() ->when($request->filled('outcome'), fn ($q) => $q->where('outcome', $request->outcome)) ->when($request->filled('user_id'), fn ($q) => $q->where('user_id', $request->user_id)) ->latest()->paginate(50); return view('admin.audit', ['logs' => $logs]); } }
Step 7. Views (Blade)
Minimal pages; style them as you like. The MFA pages are bundled (restyle with
php artisan vendor:publish --tag=password-policy-views).
{{-- resources/views/auth/login.blade.php --}} <form method="POST" action="{{ route('login') }}"> @csrf @error('email') <p style="color:#b00">{{ $message }}</p> @enderror <input type="email" name="email" value="{{ old('email') }}" placeholder="Email" required> <input type="password" name="password" placeholder="Password" required> <label><input type="checkbox" name="remember"> Remember me</label> <button>Sign in</button> <a href="{{ route('password.request') }}">Forgot password?</a> </form>
{{-- resources/views/auth/register.blade.php --}} <form method="POST" action="{{ route('register') }}"> @csrf @foreach ($errors->all() as $error) <p style="color:#b00">{{ $error }}</p> @endforeach <input name="name" value="{{ old('name') }}" placeholder="Name" required> <input type="email" name="email" value="{{ old('email') }}" placeholder="Email" required> <input type="date" name="date_of_birth" value="{{ old('date_of_birth') }}"> <input type="password" name="password" placeholder="Password" required> <input type="password" name="password_confirmation" placeholder="Confirm password" required> <button>Register</button> </form>
{{-- resources/views/auth/change-password.blade.php --}} @if ($forced) <p>You are using a temporary password. Choose a new one to continue.</p> @endif @if ($expired) <p>Your password has expired. Choose a new one to continue.</p> @endif @if (session('warning')) <p>{{ session('warning') }}</p> @endif <form method="POST" action="{{ route('password.update') }}"> @csrf @method('PUT') @foreach ($errors->all() as $error) <p style="color:#b00">{{ $error }}</p> @endforeach @if ($needCurrent) <input type="password" name="current_password" placeholder="Current password" required> @endif <input type="password" name="password" placeholder="New password" required> <input type="password" name="password_confirmation" placeholder="Confirm new password" required> <button>Change password</button> </form>
{{-- resources/views/auth/forgot-password.blade.php --}} @if (session('status')) <p>{{ session('status') }}</p> @endif <form method="POST" action="{{ route('password.email') }}"> @csrf @error('email') <p style="color:#b00">{{ $message }}</p> @enderror <input type="email" name="email" placeholder="Email" required> <button>Send reset link and code</button> </form> {{-- The emailed link opens a page that POSTs token, email, code, password and password_confirmation to route('password.reset.store'); build it the same way as the form above. --}}
{{-- resources/views/dashboard.blade.php --}} @if (session('status')) <p>{{ session('status') }}</p> @endif <h1>Welcome, {{ $user->name }}</h1> <p>Password changed: {{ $user->password_changed_at?->diffForHumans() }}</p> @can('password-policy.manage-users') <a href="{{ route('admin.users.index') }}">Manage users</a> @endcan @can('view-password-audit-logs') <a href="{{ route('admin.audit') }}">Audit log</a> @endcan <form method="POST" action="{{ route('logout') }}">@csrf <button>Log out</button></form>
{{-- resources/views/admin/users.blade.php --}} @if (session('status')) <p>{{ session('status') }}</p> @endif @foreach ($errors->all() as $error) <p style="color:#b00">{{ $error }}</p> @endforeach <form method="POST" action="{{ route('admin.users.store') }}"> @csrf <input name="name" placeholder="Name" required> <input type="email" name="email" placeholder="Company email" required> <input name="phone" placeholder="Phone (SMS fallback)"> <select name="role">@foreach (['USER','ADMIN','BA','SO','SECURITY'] as $r)<option>{{ $r }}</option>@endforeach</select> <button>Create and send temporary password</button> </form> <table> @foreach ($users as $u) @php($state = $lockout->lockState($u)) <tr> <td>{{ $u->name }} ({{ $u->role }})</td> <td>{{ $u->disabled_at ? 'Disabled' : ($state ? 'Locked: '.$state['type'] : 'Active') }}</td> <td> @foreach (['temp' => 'Send temporary password', 'lock' => 'Lock', 'unlock' => 'Unlock', 'disable' => 'Disable', 'enable' => 'Enable', 'compromised' => 'Compromised', 'offboard' => 'Offboard'] as $action => $label) <form method="POST" action="{{ route('admin.users.'.$action, $u) }}" style="display:inline"> @csrf <button>{{ $label }}</button> </form> @endforeach </td> </tr> @endforeach </table> {{ $users->links() }}
{{-- resources/views/admin/audit.blade.php --}} <table> @foreach ($logs as $log) <tr><td>{{ $log->created_at }}</td><td>{{ $log->event }}</td><td>{{ $log->outcome }}</td> <td>{{ $log->user_id }}</td><td>{{ $log->ip_address }}</td></tr> @endforeach </table> {{ $logs->links() }}
Step 8. Gates, vault and logging: app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Gate; public function boot(): void { // Everything below is DENIED to everyone until you define it. foreach (['password-policy.manage-users', 'password-policy.manage-service-accounts', 'password-policy.manage-settings', 'password-policy.view-compliance', 'view-password-audit-logs'] as $ability) { Gate::define($ability, fn ($user) => $user->isSecurityOfficer()); } }
Service-account vault callback (replace the body with your real vault client; the package never stores the secret):
<?php // app/Security/VaultWriter.php namespace App\Security; use Illuminate\Contracts\Auth\Authenticatable; class VaultWriter { public function __invoke(Authenticatable $user, string $secret): void { // Vault::put("service-accounts/{$user->getAuthIdentifier()}", ['password' => $secret]); // Throw an exception to abort: the rotation is rolled back. } }
Keep secrets out of application logs. In config/logging.php:
'single' => [ 'driver' => 'single', 'path' => storage_path('logs/laravel.log'), 'tap' => [\Mainul\PasswordPolicy\Logging\RedactSensitiveData::class], ],
React to security events (optional), also in AppServiceProvider::boot():
use Illuminate\Support\Facades\{Event, Log}; use Mainul\PasswordPolicy\Events\{AccountLocked, UnusualLoginDetected}; Event::listen(AccountLocked::class, fn ($e) => Log::warning("Locked {$e->user->email} ({$e->reason}, level {$e->level})")); Event::listen(UnusualLoginDetected::class, fn ($e) => Log::warning('Unusual login', ['reasons' => $e->reasons, 'ip' => $e->ip]));
Step 9. Schedule: routes/console.php
password-policy:disable-expired is scheduled for you. Add service-account rotation reminders:
use Illuminate\Support\Facades\Schedule; Schedule::command('password-policy:rotation-due --notify')->daily();
Make sure the scheduler runs (* * * * * php /path/to/artisan schedule:run) and the queue/mail settings are valid.
Step 10. Seed demo accounts: database/seeders/DatabaseSeeder.php
use App\Models\User; use Illuminate\Support\Facades\Hash; use Mainul\PasswordPolicy\Services\ServiceAccountService; public function run(): void { User::create(['name' => 'Admin', 'email' => 'admin@acme.com', 'role' => 'ADMIN', 'password' => Hash::make('Tr1cky#Horse9!Stable')]); // 14+ chars: admin rules User::create(['name' => 'Jane Doe', 'email' => 'jane@acme.com', 'role' => 'USER', 'password' => Hash::make('Tr1cky#Horse9')]); // A bot account: owner + purpose, rotated every 90 days, never signs in interactively. $bot = User::create(['name' => 'ETL Bot', 'email' => 'etl-bot@acme.com', 'role' => 'USER', 'password' => Hash::make(str()->random(40))]); app(ServiceAccountService::class)->register($bot, owner: 'Jane Doe', purpose: 'Nightly ETL', rotationDays: 90); }
php artisan db:seed
Step 11. Turn on authenticator-app MFA (optional, Feature 10)
php artisan password-policy:totp --enable --scope=all --grace-days=7 php artisan password-policy:totp --status
Admins are always challenged. Users are sent to mfa/enroll (QR code via bacon/bacon-qr-code) and, on later
logins, to mfa/challenge. Recovery codes are shown once. For a lost phone: php artisan password-policy:totp --reset=jane@acme.com.
To use SMS/e-mail codes instead, implement MfaDriver (Feature 11).
Step 12. JSON API for a mobile app or SPA (optional)
Already on through 'api' => ['enabled' => true] in Step 3. Issue the user a Sanctum token from your own API login
(call POST /api/password-policy/login/check first so locked accounts are refused), then:
curl -H "Authorization: Bearer <token>" -H "Accept: application/json" \ https://acme-portal.test/api/password-policy/password/status
See the JSON API section for every endpoint and the admin abilities (the Gates from Step 8 already allow security officers).
Step 13. Production checks
php artisan password-policy:check # self-test; non-zero exit on failure (run it in CI) php artisan password-policy:check-defaults # accounts still on a known default password (3.9.5) php artisan password-policy:audit --limit=20 # recent audit entries
Set APP_ENV=production and serve over HTTPS so password.secure is active. Behind a proxy or load balancer
configure trusted proxies so $request->secure() is correct.
Step 14. Try it end to end
| Do this | Expect |
|---|---|
Sign in as jane@acme.com with a wrong password 5 times |
Locked for 5 minutes with one generic message; the audit log shows failure/lockout |
As admin, create a user on /admin/users |
A temporary password arrives by email (see storage/logs/laravel.log with MAIL_MAILER=log) |
| Sign in with that temporary password | Every page redirects to /password/change until it is replaced |
Change the password to one containing the user's name, to Abcd1234!x, or to a recent password |
Rejected with a message listing what is missing |
| Change the password successfully | Other browsers/tokens for the user are signed out; a password_histories row is added |
Set expiry.days to 0 or move password_changed_at back 31 days |
The user is prompted, then disabled one day later by password-policy:disable-expired |
| Click Compromised on a user | Their password is unusable, all sessions end and a change is forced |
| Click Offboard on a user who knew a service-account password | The account is disabled and the service account is rotated through VaultWriter |
Visit /admin/audit as a normal user |
403 until your Gate allows it |
Every feature of the package is covered by this walkthrough: rules (Features 1), history (2), current password
(3), expiry (4), temporary passwords (5), lockout (6), disable/enable/compromise (7), session termination (8), reset
protection (9), authenticator MFA (10, 11), admin accounts (12), service accounts (13), offboarding (14), audit log
(15), unusual-login alerts (16, set anomaly.alert_recipients), HTTPS (17) and default-password scan (18).
Commands
| Command | Purpose |
|---|---|
password-policy:check |
Self-test: hashing driver, hidden password, HTTPS in production, reset link expiry, MFA driver, admin separation, SMS dependency, TOTP enrolment count. Exits non-zero on failure. Run it in CI/deploy. |
password-policy:check-defaults [--flag] [--user=] |
Find accounts using a known default password (3.9.5). |
password-policy:disable-expired [--dry-run] |
Disable accounts unchanged past expiry plus grace. |
password-policy:rotation-due [--notify] [--rotate] |
List, notify about, or rotate overdue service accounts. |
password-policy:offboard {user} [--actor=] |
Disable a leaver and flag the shared passwords they knew. |
password-policy:totp [--enable] [--disable] [--status] [--scope=] [--grace-days=] [--reset=] [--actor=] |
Control the authenticator-app login or wipe a user's app. |
password-policy:audit [--user= --event= --outcome= --limit=] |
Show recent audit entries (server access only). |
Events
| Event | When | Properties |
|---|---|---|
Events\AccountLocked |
An account is locked | user, reason, level, minutes |
Events\PasswordCompromised |
markCompromised() ran |
user, reportedBy |
Events\UnusualLoginDetected |
Repeated failures / new network / new country | user, identifier, reasons[], ip |
// app/Providers/EventServiceProvider.php or AppServiceProvider::boot() Event::listen(AccountLocked::class, function (AccountLocked $e) { Slack::to('#security')->send("Account {$e->user->email} locked ({$e->reason}, level {$e->level})."); }); Event::listen(UnusualLoginDetected::class, fn ($e) => Log::warning('Unusual login', [ 'user' => $e->user?->getAuthIdentifier(), 'reasons' => $e->reasons, 'ip' => $e->ip, ]));
The package also listens to Laravel's Login, Failed, Lockout and PasswordReset events.
Configuration
Everything lives in config/password-policy.php and is documented inline. Groups:
| Group | Purpose |
|---|---|
rules |
Complexity, personal info, banned words, patterns |
expiry |
Max age, grace period, auto-disable |
history |
Reuse prevention |
lockout |
Attempts, durations, IP burst |
temporary_password |
Length, delivery order/channels, company domains |
reset |
Restricted roles, role resolver, one-time codes, notice |
anomaly |
Unusual-login thresholds, geo resolver, alert recipients |
tls |
HTTPS enforcement, forbidden query keys |
audit |
Enable, gate ability, redaction keys |
mfa, totp |
MFA scope, driver, authenticator-app options |
api |
Enable, guard, prefix, throttle, abilities |
admin |
Admin identification and stricter values |
service_accounts |
Rotation, vault, recipients |
defaults |
Known default passwords |
sessions |
Terminate on password change |
columns |
User column names (email, phone, name, birthdate) |
current_password |
When the current-password rule is skipped |
middleware |
Excluded routes/paths and the change-password route |
user_model |
Your User class |
Common recipes
// Relaxed, e.g. an internal tool: 12 chars, 90-day expiry, no personal-info check 'rules' => ['min_length' => 12, 'forbid_personal_info' => false], 'expiry' => ['days' => 90], // Different column names 'columns' => ['email' => 'work_email', 'phone' => 'mobile', 'name' => 'full_name', 'birthdate' => 'dob'], // Admin flag stored in a role column 'admin' => ['roles' => ['ADMIN'], 'flag_attribute' => null], // Turn a feature off 'lockout' => ['enabled' => false], 'history' => ['enabled' => false], 'audit' => ['enabled' => false], 'sessions' => ['terminate_on_password_change' => false],
HTTPS enforcement (tls.enforce = null) is active only when APP_ENV=production; set true/false to force it.
Things to know before relying on it
- Shared cache: the IP-burst counter, repeated-failure counter and API MFA state use the cache. On more
than one server use a shared store (Redis or database), not
arrayorfile. - Lockout wording: policy clause 3.4.2 does not define "second occurrence" or "extended temporary lockout".
The defaults are an interpretation and are configurable. With the default IP burst (5 in 60 s) a person who
mistypes 5 times in a minute is locked until an administrator unlocks them. Raise
lockout.ip_burst.attemptsif that is too strict. - MFA factor: until you enable the built-in app (
totp.enabled) or provide anMfaDriver, users who need MFA are blocked. - Self-reset block: the response for a restricted role (BA, SO) reveals that the account exists and has that role. Unknown emails get the normal answer.
- Delivery is synchronous: temporary passwords, reset notices and alerts are sent inline, not queued.
- Admin defaults are an assumption: minimum length 14, expiry 60 days, history 5.
- Not enforceable in code: sharing or writing down passwords, reusing a password across systems, browser "Remember Password", keeping an admin password different from the same person's user-account password.
APP_KEY: TOTP secrets are encrypted with it. Do not rotate it casually.
Policy compliance
Legend: ✅ implemented by the package · 🔌 implemented, but needs your wiring or a host-supplied part · 🅻 relies on Laravel itself, the package verifies or adds to it · ➖ outside what a package can do.
| Clause | Requirement | Status | Where |
|---|---|---|---|
| 3.1.1 | Identity verified via form FRM-001 | ➖ | Business process |
| 3.1.2 | Random, unpredictable temporary password | ✅ | TemporaryPasswordService |
| 3.1.3 | Secure channel: company email, else registered phone | 🔌 | Mail; SMS needs xenon/laravelbdsms |
| 3.1.4 | Never an unprotected channel | ✅ | No fallback; NoSecureChannelException |
| 3.1.5 | Forced change at first login | 🔌 | password.force_change middleware |
| 3.1.6 | Temporary password cannot stay permanent | ✅ | Trait + history |
| 3.2.1–3.2.3 | Hashed, salted, never plaintext | 🅻 | Laravel hashing; password-policy:check verifies the driver |
| 3.2.4 | Password masked everywhere | 🔌 | $hidden check, audit redaction, log tap |
| 3.2.5–3.2.6 | No hard-coded secrets, use a vault | ➖ | Developer practice |
| 3.3.1 | TLS only | 🔌 | password.secure, production only |
| 3.3.2 | No passwords in URLs/query strings | 🔌 | password.secure (query string; headers are not inspected) |
| 3.4.1 | Limit consecutive failures | 🔌 | LockoutService + LoginGuard |
| 3.4.2 | Tiered, extended and IP-burst lockout | 🔌 | LockoutService + LoginGuard |
| 3.4.3 | MFA enforced for admin, remote, external | 🔌 | password.mfa + authenticator app or your MfaDriver |
| 3.4.4 | MFA available for standard users | 🔌 | mfa.require_all or totp.scope = all + a driver |
| 3.5.1 | Max age, prompt, disable 1 day later | ✅ | Expiry middleware, disable-expired, password.account_active |
| 3.5.2 | Old password invalid after change | ✅ | Trait ends other sessions and tokens |
| 3.5.3 | Password history | ✅ | PasswordNotReusedRule |
| 3.5.4 | Current password for voluntary change | 🔌 | CurrentPasswordRule |
| 3.6.1 | Self-service reset | 🅻 | Laravel password broker |
| 3.6.2 | Independent identity check on reset | 🔌 | ResetIdentityVerifier (one-time code) |
| 3.6.3 | Short-lived, single-use links | 🅻 | Laravel broker; password-policy:check verifies expiry |
| 3.6.4 | Never email a password on reset | 🅻 | Laravel broker; notices never contain a password |
| 3.6.5 | Notify the user after a reset | ✅ | NotifyPasswordReset |
| 3.6.6 | BA/SO cannot self-reset | 🔌 | password.block_self_reset, CanSelfResetPassword |
| 3.7.1 | Log logins, changes, resets | ✅ | AuditLogger (reset requests only on Laravel versions that fire the event) |
| 3.7.2 | No secrets in logs | ✅ | Audit redaction; 🔌 log tap for application logs |
| 3.7.3 | Restricted log access | 🔌 | Gate denies until you define it |
| 3.7.4 | Unusual-login monitoring and alerts | ✅ | AnomalyDetector |
| 3.7.5 | Force reset, end all sessions on compromise | ✅ | AccountService::markCompromised() |
| 3.8.1–3.8.2 | Role-change forms and approvals | ➖ | Business process |
| 3.8.3 | Disable a leaver the same day | ✅ | AccountService::disable(), password-policy:offboard |
| 3.8.4 | Terminate sessions and tokens | 🔌 | SessionTerminator + password.session_version |
| 3.8.5 | Rotate passwords a leaver knew | ✅ | Offboarding marks service accounts due; rotation needs your vault |
| 3.9.1 | Admin accounts separate from daily accounts | 🔌 | Detected by password-policy:check, not enforced |
| 3.9.2 | Stronger admin passwords, MFA always | 🔌 | PasswordPolicyRule::for($user); MFA needs a driver |
| 3.9.3 | Service accounts: owner and purpose | ✅ | ServiceAccount |
| 3.9.4 | Vaulted, rotating service passwords | 🔌 | Rotation here; the vault is yours |
| 3.9.5 | Change defaults before go-live | ✅ | password-policy:check-defaults |
Testing
composer install vendor/bin/phpunit
The suite uses Orchestra Testbench. In your own tests you can fake delivery and MFA by binding your own classes
(see tests/Support/FakeSmsChannel.php, FakeMfaDriver.php, FakeGeoResolver.php for ready-made examples).
Upgrading
- Run
php artisan migrateafter every update. - Re-publish or merge the config to see new options:
php artisan vendor:publish --tag=password-policy-config --force(this overwrites your edits, so diff first). Defaults apply without it. - Stricter defaults (11 characters, 30-day expiry, 5-password history, personal-info/banned-word/pattern checks) apply at the next password change. Set the old values in your published config to keep them.
- See CHANGELOG.md.
License
MIT
বাংলা ডকুমেন্টেশন
mainul/password-policy হলো Laravel-এর জন্য একটি প্যাকেজ, যা পাসওয়ার্ড ও অ্যাকাউন্ট নিরাপত্তার বিভিন্ন নিয়ন্ত্রণ বাস্তবায়ন করে: ভ্যালিডেশন রুল, মেয়াদ, ইতিহাস, লকআউট, অস্থায়ী পাসওয়ার্ড, MFA, অডিট লগ, সার্ভিস অ্যাকাউন্ট এবং JSON API।
এর জন্য PHP 8.2+ এবং Laravel 10 থেকে 13 প্রয়োজন।
প্যাকেজটি প্রয়োজনীয় নিয়ন্ত্রণ সরবরাহ করে। তবে কিছু নিয়ন্ত্রণ কার্যকর করতে আপনার অ্যাপ্লিকেশনে middleware, login action এবং Gate যুক্ত করতে হবে। নিচের প্রতিটি অংশে তা ব্যাখ্যা করা হয়েছে। একই ফাইল অপ্রয়োজনীয়ভাবে বড় ও দুই ভাষার code block অসামঞ্জস্যপূর্ণ হয়ে যাওয়া এড়াতে executable code, command, route, configuration key এবং API payload উপরের English অংশে একবারই রাখা হয়েছে। প্রতিটি বাংলা অংশের নম্বর সংশ্লিষ্ট English অংশের সঙ্গে সরাসরি মিলে যায়।
সূচিপত্র
- বৈশিষ্ট্য
- ইনস্টলেশন
- দ্রুত শুরু
- বৈশিষ্ট্য নির্দেশিকা
- JSON API
- সম্পূর্ণ উদাহরণ (MVC)
- Artisan command
- Event
- কনফিগারেশন
- ব্যবহারের আগে গুরুত্বপূর্ণ বিষয়
- নীতি-সম্মতি
- পরীক্ষা, আপগ্রেড ও লাইসেন্স
বৈশিষ্ট্য
- Password rules: দৈর্ঘ্য, বড়/ছোট অক্ষর, সংখ্যা, বিশেষ চিহ্ন, ব্যক্তিগত তথ্য, নিষিদ্ধ শব্দ এবং সহজ pattern পরীক্ষা করে। Admin-এর জন্য আরও কঠোর rule প্রযোজ্য।
- Password history: সাম্প্রতিক পাসওয়ার্ড পুনরায় ব্যবহার বন্ধ করে।
- Temporary password: নিরাপদ random password তৈরি করে অনুমোদিত email/SMS channel-এ পাঠায় এবং প্রথম login-এ পরিবর্তন বাধ্যতামূলক করে।
- Account lockout: ধাপভিত্তিক lock period, administrator unlock এবং দ্রুত IP-based failure শনাক্ত করে।
- Password expiry: ব্যবহারকারীকে পরিবর্তনের বার্তা দেয় এবং অতিরিক্ত মেয়াদোত্তীর্ণ account স্বয়ংক্রিয়ভাবে disable করে।
- Session termination: password change, compromise বা offboarding-এর পরে web session ও API token শেষ করে।
- Audit ও monitoring: security event record করে, secret মুছে রাখে এবং unusual login শনাক্ত করে।
- MFA: built-in authenticator app (TOTP) অথবা custom driver সমর্থন করে।
- Reset protection: one-time identity code এবং role-based reset restriction দেয়।
- Service account: owner, purpose এবং vault-এর মাধ্যমে scheduled rotation পরিচালনা করে।
- Offboarding ও command: চলে যাওয়া কর্মীর account disable, shared credential flag এবং diagnostic চালায়।
- JSON API: mobile app ও SPA-এর জন্য HTTP interface দেয়; default Sanctum, Passport-ও সমর্থিত।
ইনস্টলেশন
উপরের Installation অংশের command চালান। Service provider auto-discover হবে। ঐচ্ছিক package-গুলোর কাজ:
| Package | ব্যবহার |
|---|---|
bacon/bacon-qr-code |
authenticator setup page-এ QR code দেখায়; না থাকলে key দেখায় |
xenon/laravelbdsms |
company email না থাকলে SMS-এ temporary password/reset code পাঠায় |
laravel/sanctum |
JSON API-এর default guard |
laravel/passport |
বিকল্প API guard |
Publish tag দিয়ে config, migration এবং MFA view প্রকাশ করা যায়। Migration users table-এ password state, lockout ও session-version column যোগ করে এবং history, audit, known login, reset code, service account, MFA credential ও runtime setting-এর table তৈরি করে। users table-এর নাম নির্দিষ্ট। পুরোনো user যেন সঙ্গে সঙ্গে expired না হয়, তাই migration-এর সময় তাদের password_changed_at বসানো হয়।
দ্রুত শুরু
সাধারণ Laravel app-এ ন্যূনতম ছয়টি integration দরকার:
- User model:
HasPasswordPolicytrait ব্যবহার করুন এবংpassword,remember_tokenhidden রাখুন। Trait history সংরক্ষণ, change time লেখা, forced-change flag, অন্য session বন্ধ এবং audit entry তৈরি করে। Model অন্য namespace-এ থাকলেpassword-policy.user_modelবদলান। - Route: authenticated route-এ
password.account_active,password.session_version,password.expiry,password.force_changeওpassword.mfamiddleware দিন। Password change ও logout route-কে excluded route হিসেবে reachable রাখুন। Login/reset route-এpassword.secure; restricted self-reset route-এpassword.block_self_resetদিন। - Login action: credential পরীক্ষা করার আগে
LoginGuard::ensureCanAttempt()চালান। Locked, disabled ও expired account-এর জন্য user-কে একই generic message দেখান। Laravel-এরFailedওLoginevent counter ও audit স্বয়ংক্রিয়ভাবে চালায়। - Password change form:
CurrentPasswordRule,PasswordPolicyRule::for($user)এবংPasswordNotReusedRuleব্যবহার করুন। Field-এর সঙ্গেrequired-ও দিন। Trait update-এর পর বাকি security কাজ করে। - Schedule:
password-policy:disable-expiredদৈনিক স্বয়ংক্রিয়ভাবে schedule হয়। Service-account notification/rotation command নিজে schedule করুন। - Gate: audit log এবং API admin access default-এ সবার জন্য denied। উপরের English example অনুযায়ী Gate define করুন।
Middleware alias-গুলোর উদ্দেশ্য:
| Alias | কাজ |
|---|---|
password.expiry |
expired password হলে redirect অথবা JSON 403 |
password.force_change |
temporary password বদলানো পর্যন্ত অন্য কাজ block |
password.account_active |
disabled/overdue account logout |
password.session_version |
পুরোনো session invalid |
password.mfa |
দ্বিতীয় factor বাধ্যতামূলক |
password.secure |
HTTPS নিশ্চিত এবং URL query-তে secret বন্ধ |
password.block_self_reset |
restricted role-এর self-reset বন্ধ |
বৈশিষ্ট্য নির্দেশিকা
১. Password rule
PasswordPolicyRule password-policy.rules config অনুযায়ী minimum length, character class, personal information, banned word এবং repeated/sequential pattern পরীক্ষা করে। User দিলে admin profile ও personal-info check প্রযোজ্য; user না দিলে global rule চলে এবং personal-info check বাদ যায়। Registration-এ password_policy string alias ব্যবহার করা যায়। Custom validation message lang file-এ দিন। Company name বা প্রচলিত দুর্বল শব্দ rules.banned_words-এ যোগ করুন। Birthdate/name/email/phone field-এর mapping columns.* থেকে আসে। Tinker example উপরের Password rules অংশে আছে।
২. Password history
Default-এ history চালু এবং শেষ ৫টি password পুনঃব্যবহার নিষিদ্ধ। Password বদলালে trait পুরোনো hash password_histories-এ রাখে; PasswordNotReusedRule নতুন plain password-কে শেষ Nটি hash-এর সঙ্গে পরীক্ষা করে। Admin-এর জন্য admin.history_count প্রযোজ্য এবং কঠোরতর মানটি নেওয়া হয়। Programmatic check-এর জন্য $user->hasUsedPassword(...) ব্যবহার করুন।
৩. Current-password confirmation
স্বেচ্ছায় password বদলাতে বর্তমান password জানা প্রমাণ করতে CurrentPasswordRule ব্যবহার করুন। Temporary password বা expired password-এর বাধ্যতামূলক change-এ config অনুযায়ী rule skip হতে পারে। Administrator অন্যের password reset করলে rule প্রয়োগ করবেন না। Forced flow-তে current_password field-কে নিঃশর্ত required করবেন না।
৪. Password expiry
expiry.enabled, days, grace_days ও auto_disable দিয়ে নিয়ন্ত্রণ করুন। password.expiry middleware expired user-কে change page-এ পাঠায় বা JSON 403 password_expired দেয়। Grace period পার হলে scheduler, command অথবা middleware account disable করতে পারে। PasswordExpiryService দিয়ে expired/disable-due পরীক্ষা এবং ExpiredAccountSweeper দিয়ে dry run বা sweep করা যায়। Service account expiry নয়, rotation schedule অনুসরণ করে।
৫. Temporary password
Administrator account তৈরি বা reset করলে TemporaryPasswordService::issueFor() random policy-compliant password বানিয়ে approved channel-এ পাঠায়; password কখনও return করে না এবং প্রথম login-এ change বাধ্যতামূলক হয়। Company email অগ্রাধিকার পায়, email না থাকলে registered phone; insecure fallback নেই। Valid channel না থাকলে NoSecureChannelException, delivery ব্যর্থ হলে DeliveryFailedException এবং transaction rollback হয়। Custom WhatsApp/Slack channel-এর জন্য PasswordDeliveryChannel implement করুন। Test/seeding-এর জন্য শুধু generate করা যায়, কিন্তু production delivery flow-তে plain password log করবেন না।
User তৈরির সময় স্বয়ংক্রিয়ভাবে (default-এ বন্ধ): temporary_password.auto_issue_on_create => true দিলে HasPasswordPolicy ব্যবহারকারী model-এ নতুন user তৈরির সঙ্গে সঙ্গে temporary password issue ও deliver হয়। create()-এ দেওয়া password এটি প্রতিস্থাপন করে, তাই column বাধ্যতামূলক হলে যেকোনো placeholder দিন। Channel না থাকলে বা delivery ব্যর্থ হলে user তৈরি আটকায় না; error report() ও audit হয়, পরে issueFor() দিয়ে আবার পাঠানো যায়। কিছু user (যেমন নিজে registration করা) বাদ দিতে model-এ shouldIssueTemporaryPassword() override করুন।
৬. Account lockout
Default tiered lockout consecutive failure-এর পরে ৫, ১০ ও ৩০ মিনিট; পরেরগুলো ১২০ মিনিট ও identity verification চাইতে পারে। একই account-এ এক IP থেকে ৬০ সেকেন্ডে ৫ failure হলে default-এ administrator unlock না করা পর্যন্ত permanent lock হয়। Login credential check-এর আগে LoginGuard ব্যবহার করতে হবে। UI-তে generic error দেখান; internal log-এ exception-এর reason ও retryAfterSeconds রাখা যায়। LockoutService state দেখা, manual lock ও verified unlock সমর্থন করে। CLI unlock নেই; service বা admin API ব্যবহার করুন।
৭. Disable, enable ও compromised account
AccountService::disable() login block ও session শেষ করে। enable() account চালু করে কিন্তু password change বাধ্যতামূলক করে। markCompromised() password unusable করে, সব session/token শেষ করে, change force করে এবং PasswordCompromised event পাঠায়। Identity verify করার পরে temporary password issue করুন।
৮. Session termination
Password বদলালে trait user-এর অন্য web session ও API token শেষ করে; যে session change করেছে সেটি চালু থাকে। sessions.terminate_on_password_change = false দিয়ে বন্ধ করা যায়। SessionTerminator সব session অথবা current session রেখে বাকিগুলো শেষ করতে পারে। এটি session_version বাড়ায়, database session পরিষ্কার করে এবং Sanctum/Passport token মুছে দেয়; route-এ password.session_version middleware থাকা জরুরি।
৯. Password reset protection
reset.restricted_roles, role_attribute অথবা custom role_resolver দিয়ে BA/SO-এর মতো role-এর self-reset বন্ধ করুন। Forgot-password route-এ middleware বা CanSelfResetPassword rule দিন। স্বাধীন পরিচয় যাচাইয়ের জন্য ResetIdentityVerifier একবার ব্যবহারযোগ্য code company email বা phone-এ পাঠায়; default ১০ মিনিট মেয়াদ, ৫টি ভুল চেষ্টার পরে lock। সফল reset-এর পরে Laravel PasswordReset event পাঠালে audit ও password-reset notice হয়; notice-এ password থাকে না। password-policy:check broker link expiry সর্বোচ্চ ৬০ মিনিটের মধ্যে আছে কি না পরীক্ষা করে।
১০. Authenticator-app MFA (TOTP)
Google/Microsoft Authenticator, Authy ইত্যাদির ৬-digit code দ্বিতীয় factor হিসেবে ব্যবহার করা যায়। এটি default-এ বন্ধ। Enable করলে scope অনুযায়ী প্রয়োজনীয় হয় এবং app না থাকা user setup page-এ যায়। Bundled route/view ব্যবহার করতে totp.routes চালু করে password.mfa middleware দিন; অথবা TotpEnrollmentService ও MfaService দিয়ে নিজস্ব UI বানান। Enrollment secret/URI দেখিয়ে code confirm করুন; recovery code মাত্র একবার দেখান। Challenge TOTP বা recovery code গ্রহণ করে এবং ভুল code lockout count বাড়ায়।
password_policy_settings table-এর totp.enabled, scope, grace_days, issuer config-কে override করে; command বা admin API দিয়ে audited change করা যায়। Code-এ policy pin করতে totp.enabled ও totp.lock_to_config দুটোই true করুন। Scope all, admins বা trusted network-এর বাইরে remote; admin-এর MFA সবসময় প্রয়োজন। Secret APP_KEY দিয়ে encrypted, recovery code keyed hash, replay blocked, সফল verify-তে session ID renew হয়। APP_KEY বদলালে পুরোনো secret পড়া যাবে না। Settings table unavailable হলে config fallback ব্যবহৃত হয়।
১১. Custom MFA driver
SMS, email OTP বা push দরকার হলে MfaDriver implement করে mfa.driver-এ class দিন; custom driver built-in driver-এর আগে প্রাধান্য পায়। Admin সবসময়, require_remote হলে trusted network-এর বাইরের user, এবং require_all হলে সবাই MFA ব্যবহার করবে। Factor না থাকলে fail-closed হিসেবে access block হবে। External driver থাকলে built-in enrollment endpoint 404 mfa_external_driver দেয়, কারণ enrollment host driver-এর দায়িত্ব। OTP single-use ও স্বল্পমেয়াদি রাখুন।
১২. Admin account
admin.roles অথবা truthy admin.flag_attribute দিয়ে admin শনাক্ত হয়। Global ও admin config-এর মধ্যে কঠোরতর minimum length, expiry ও history মান প্রয়োগ হয়। Default example-এ ১৪+ character, ৬০ দিনের expiry ও ৫ password history আছে। daily_email_domains-এ থাকা সাধারণ-use email দিয়ে admin login করলে password-policy:check তা flag করে, যাতে privileged ও দৈনন্দিন account পৃথক রাখা যায়।
১৩. Service account ও rotation
Bot/integration account-এর named owner, purpose ও rotation schedule থাকা দরকার এবং interactive login করা উচিত নয়। ServiceAccountService register, update, due list, notification, vault rotation ও remove সমর্থন করে। knownBy-তে যাদের user ID আছে, তাদের কাউকে offboard করলে account অবিলম্বে rotation-due হয়। Package secret রাখে বা return করে না; configured vault callback না থাকলে rotation প্রত্যাখ্যান করে এবং vault ব্যর্থ হলে database change rollback করে। rotation-due command দিয়ে list, notify বা rotate করুন।
১৪. কর্মী offboarding
password-policy:offboard command অথবা OffboardingService একই দিনে account disable করে, সব session/token শেষ করে এবং ব্যক্তি যে service-account password জানতেন সেগুলো rotation-due করে। Returned collection-এর প্রতিটি account vault-এর মাধ্যমে rotate করুন।
১৫. Audit log
Login, failure, lockout, password change/reset, MFA ও admin action password_audit_logs-এ লেখা হয়। audit.redact_keys-এর password, token, code, OTP ইত্যাদি secret redacted থাকে। পড়ার access default-এ denied; view-password-audit-logs Gate define করুন। Model দিয়ে query, AuditLogger দিয়ে custom entry এবং Artisan command দিয়ে filter করা যায়। Application log-এর জন্য RedactSensitiveData tap যোগ করুন; array পরিষ্কারে Redactor::redact() আছে।
১৬. Unusual-login detection
নির্ধারিত সময়ে failure threshold পার হলে, নতুন IPv4 /24 বা IPv6 /48 network থেকে সফল login হলে, অথবা resolver থাকলে নতুন country থেকে login হলে alert হয়। প্রথম login শুধু baseline তৈরি করে। Alert audit হয়, configured recipient-কে email যায় এবং UnusualLoginDetected event dispatch হয়। Country check-এর জন্য নিজের GeoResolver দিন; package কোনো external geo service bundle করে না।
১৭. নিরাপদ HTTPS transport
password.secure non-HTTPS request এবং query string-এ password/current_password-এর মতো secret প্রত্যাখ্যান করে। Default-এ কেবল APP_ENV=production-এ সক্রিয়; tls.enforce দিয়ে force on/off করা যায়। Login, password ও reset route-এ middleware দিন। Proxy/load balancer-এর পেছনে Laravel trusted proxy সঠিকভাবে configure করুন, যাতে $request->secure() যথার্থ ফল দেয়।
১৮. Default-password scan
Go-live-এর আগে defaults.passwords-এ vendor/default password যোগ করে password-policy:check-defaults চালান। --flag matching user-কে password change-এ বাধ্য করে; --user একটি user পরীক্ষা করে। প্রতিটি candidate প্রতিটি user-এর hash-এর সঙ্গে যাচাই হওয়ায় বড় database-এ এটি ধীর—off-peak সময়ে চালান।
JSON API
Mobile app, SPA ও service-এর জন্য একই feature HTTP-তে পাওয়া যায়। API default-এ বন্ধ; api.enabled config বা runtime setting চালু না করা পর্যন্ত route 404 দেয়। Default guard sanctum; Passport ব্যবহার করলে passport driver-এর guard দিন। Guard list দিলে ক্রমানুসারে চেষ্টা হয়। Database setting প্রতি request-এ config-কে override করে।
Admin endpoint-এর Gate default-এ সবাইকে deny করে। Manage users, service accounts, settings, compliance ও audit-এর Gate define করুন। Default-এ admin route expiry, forced-change ও MFA middleware-এর পেছনে থাকে। Prefix default /api/password-policy; error সাধারণত message/error অথবা Laravel validation errors format-এ আসে। Anonymous ও secret-checking endpoint আলাদা throttle ব্যবহার করে।
Endpoint group-গুলোর সারাংশ:
| Group | কাজ |
|---|---|
login/check, reset/* |
anonymous pre-login check ও one-time-code reset |
policy, password/* |
বর্তমান policy/status, validation ও password change |
mfa/* |
status, enrollment, challenge, verification ও recovery code |
admin/users/* |
state, known login, lock/unlock, disable/enable, compromise, temporary password, session termination, offboarding ও MFA reset |
admin/service-accounts/* |
list, register, update, remove, rotate ও notification |
admin/settings |
database override পরিচালনা |
admin/audit, admin/compliance/* |
audit query, self-test ও default-password scan |
সম্পূর্ণ method/path, request field, response, curl flow এবং mobile MFA example উপরের Endpoints ও Examples অংশে আছে। API token-এর MFA verification cache-এ token-ভিত্তিকভাবে default ১২ ঘণ্টা থাকে; বহু server-এ shared cache ব্যবহার করুন। Reset code user-dependent check-এর আগে spent হয়, তাই failed attempt-এর পরে নতুন code চাইতে হবে। Login action নিজে এবং Laravel reset-link flow এই API-এর অংশ নয়।
সম্পূর্ণ উদাহরণ (MVC)
একটি একদম নতুন Laravel প্রজেক্টে প্যাকেজের সব বৈশিষ্ট্য ব্যবহারের ধাপে ধাপে উদাহরণ উপরের English অংশের Complete example সেকশনে আছে। এতে Model (User), View (Blade), Controller ও Form validation MVC কাঠামোতে সাজানো: প্রজেক্ট তৈরি ও ইনস্টল, migration, config, route, login/register/change-password/forgot-password controller, admin user management (temporary password, lock/unlock, disable, compromise, offboard), audit log, Gate, vault, schedule, seeder, MFA, JSON API এবং production check। ধাপগুলো ক্রমানুযায়ী অনুসরণ করুন।
Artisan command
| Command | উদ্দেশ্য |
|---|---|
password-policy:check |
hashing, hidden password, HTTPS, reset expiry, MFA, admin separation, SMS dependency ও enrollment self-test; CI/deploy-এ চালান |
password-policy:check-defaults |
পরিচিত default password খুঁজে flag করে |
password-policy:disable-expired |
grace period পার হওয়া account dry-run/disable করে |
password-policy:rotation-due |
overdue service account list, notify বা rotate করে |
password-policy:offboard |
কর্মীর account disable ও shared password rotation flag করে |
password-policy:totp |
authenticator policy enable/disable/status/scope/reset পরিচালনা করে |
password-policy:audit |
সাম্প্রতিক audit entry filter করে দেখায় |
Event
AccountLocked: account lock হলেuser,reason,level,minutesদেয়।PasswordCompromised:markCompromised()চললেuser,reportedByদেয়।UnusualLoginDetected: repeated failure/new network/new country হলেuser,identifier,reasons,ipদেয়।
Listener দিয়ে Slack/SOC alert বা নিজস্ব logging করা যায়। Package Laravel-এর Login, Failed, Lockout ও PasswordReset event-ও শোনে।
কনফিগারেশন
সব option config/password-policy.php-এ inline documented। প্রধান group: rules, expiry, history, lockout, temporary_password, reset, anomaly, tls, audit, mfa, totp, api, admin, service_accounts, defaults, sessions, columns, current_password, middleware, user_model। Relaxed rule, custom column, role-based admin detection এবং feature off করার recipe উপরের Configuration অংশে আছে। tls.enforce = null শুধু production-এ HTTPS enforce করে; সব environment-এ চালাতে true, বন্ধ করতে false দিন।
ব্যবহারের আগে গুরুত্বপূর্ণ বিষয়
- Shared cache: IP burst, repeated failure ও API MFA state cache-এ থাকে। বহু server-এ Redis/database ব্যবহার করুন;
array/fileনয়। - Lockout wording: policy-র কিছু শব্দের বাস্তবায়ন configurable interpretation। Default IP burst খুব কঠোর হতে পারে; প্রয়োজনে attempt বাড়ান।
- MFA factor: built-in TOTP বা custom driver চালু না থাকলে MFA-required user block হবে।
- Self-reset disclosure: restricted role-এর response account/role আছে বলে ইঙ্গিত দিতে পারে; unknown email স্বাভাবিক response পায়।
- Synchronous delivery: temporary password, reset notice ও alert inline পাঠানো হয়, queued নয়।
- Admin default: ১৪ character, ৬০-day expiry ও ৫-history একটি default assumption।
- Code-এর বাইরে: password share/লিখে রাখা, অন্য system-এ reuse, browser save এবং একই ব্যক্তির admin/daily password আলাদা রাখা package দিয়ে পুরোপুরি enforce করা যায় না।
APP_KEY: TOTP secret এটি দিয়ে encrypted; অসতর্কভাবে rotate করবেন না।
নীতি-সম্মতি
Status legend: ✅ package-এ সম্পূর্ণ · 🔌 host application wiring/implementation দরকার · 🛡 Laravel বাস্তবায়ন করে, package যাচাই বা সম্পূরক নিয়ন্ত্রণ দেয় · ➖ business process/package-এর বাইরের বিষয়। Clause 3.1–3.9-এর পূর্ণ requirement, status ও implementation mapping উপরের Policy compliance table-এ অপরিবর্তিতভাবে রাখা হয়েছে, যাতে audit reference ও clause number একটিই authoritative source থাকে। প্রধান wiring dependency হলো middleware, login guard, Gate, MFA driver, vault এবং trusted proxy; business form/approval ও human password আচরণ application package-এর বাইরে।
পরীক্ষা, আপগ্রেড ও লাইসেন্স
composer install এবং vendor/bin/phpunit চালিয়ে test করুন। Suite Orchestra Testbench ব্যবহার করে; delivery, MFA ও Geo resolver-এর fake class tests/Support-এ example হিসেবে আছে। প্রতিটি update-এর পরে migration চালান। নতুন config option পেতে publish/merge করুন; --force existing edit overwrite করে, তাই আগে diff করুন। নতুন কঠোর default পরবর্তী password change-এ প্রযোজ্য—পুরোনো behavior রাখতে published config-এ পুরোনো মান স্পষ্টভাবে দিন। পরিবর্তনের তালিকা CHANGELOG.md-এ। License: MIT।