Download the PHP package coding-libs/laravel-mfa without Composer

mfa

Multi Factor Authentication CodingLibs Laravel MFA

Installation

• Install via Composer from Packagist:

• The service provider auto-registers. Publish config and migrations:

Features

• Email and SMS one-time code challenges with pluggable channels
• Configurable channel classes - extend Email and SMS channels via configuration
• Challenge generation without sending - generate codes without automatic delivery
• Google Authenticator compatible TOTP (RFC 6238) setup and verification
• Built-in QR code generation to display TOTP provisioning URI (uses bacon/bacon-qr-code)
• Remember device support via secure, hashed tokens stored in mfa_remembered_devices
• Recovery Codes: generate, verify, and manage one-time backup codes
• Simple API via MFA facade/service for issuing and verifying codes
• Publishable config and migrations; encrypted storage of TOTP secret
• Extendable channel system to add providers like WhatsApp, Twilio, etc.

MFA Channels

• Email: delivers a one-time code via Laravel Mail
• SMS: delivers a one-time code via the configured SMS driver (defaults to log)
• TOTP: time-based one-time password compatible with Google Authenticator and similar apps

Compatibility

• Laravel 11 and 12
• PHP >= 8.2

Usage

Remember Devices (Optional)

• Enable or configure in config/mfa.php under remember (or via env: see below)
• On successful MFA, call MFA::rememberDevice(...) and attach the returned cookie to the response
• On subsequent requests, use MFA::shouldSkipVerification($user, MFA::getRememberTokenFromRequest($request))
• To revoke a remembered device, call MFA::forgetRememberedDevice($user, $token)

Recovery Codes

• What they are: single‑use backup codes that let users complete MFA when they cannot access their primary factor (e.g., lost phone or no network).
• Storage and security:
  • Plaintext codes are returned only once at generation time; only their hashes are stored in mfa_recovery_codes.
  • Hashing algorithm is configurable via mfa.recovery.hash_algo (default sha256).
  • Codes are marked as used at first successful verification and cannot be reused.

• Generating and displaying to the user:

• Verifying a code and optional regeneration-on-use:

• Pool size maintenance: set mfa.recovery.regenerate_on_use = true to automatically replace a consumed code with a new one so the remaining count stays steady.

• Managing codes:

• UX recommendations:
  • Require the user to confirm they’ve saved the codes before leaving the setup screen.
  • Offer copy, download (txt), and print actions. Avoid storing plaintext on your servers.
  • Warn that each code is one-time and will be invalid after use.

Configuration

• See config/mfa.php for all options. Key settings:
  • code_length: OTP digits for email/sms (default 6)
  • code_ttl_seconds: Challenge expiry (default 300s)
  • email:
  • enabled (bool)
  • from_address, from_name, subject
  • channel: custom channel class (default: EmailChannel)
  • sms:
  • enabled (bool)
  • driver: log (default) or custom integration
  • from: optional sender id/number
  • channel: custom channel class (default: SmsChannel)
  • totp:
  • issuer: defaults to config('app.name')
  • digits: 6 by default
  • period: 30s by default
  • window: 1 slice tolerance by default
  • remember:
  • enabled (bool, default true)
  • cookie: cookie name (default mfa_rd)
  • lifetime_days: validity window (default 30)
  • path, domain, secure, http_only, same_site
  • recovery:
  • enabled (bool, default true)
  • codes_count: number of codes to generate (default 10)
  • code_length: length of each code (default 10)
  • regenerate_on_use: whether to auto-regenerate when consumed (default false)
  • hash_algo: hashing algorithm for stored codes (default sha256)

Environment variables (examples)

Database

• Publishing migrations creates tables:
  • mfa_methods: tracks enabled MFA methods per user; stores encrypted TOTP secret
  • mfa_challenges: stores pending OTP codes for email/sms with expiry and consumed_at
  • mfa_remembered_devices: stores hashed tokens for device recognition with IP, UA, and expiry
  • mfa_recovery_codes: stores hashed recovery codes and usage timestamp

API Overview (Facade MFA)

• issueChallenge(Authenticatable $user, string $method, bool $send = true): ?MfaChallenge
• generateChallenge(Authenticatable $user, string $method): ?MfaChallenge - Generate without sending
• verifyChallenge(Authenticatable $user, string $method, string $code): bool
• setupTotp(Authenticatable $user, ?string $issuer = null, ?string $label = null): array returns ['secret','otpauth_url']
• verifyTotp(Authenticatable $user, string $code): bool
• generateTotpQrCodeBase64(Authenticatable $user, ?string $issuer = null, ?string $label = null, int $size = 200): ?string
• isEnabled(Authenticatable $user, string $method): bool
• enableMethod(Authenticatable $user, string $method, array $attributes = []): MfaMethod
• disableMethod(Authenticatable $user, string $method): bool
• Remember device helpers:
  • isRememberEnabled(): bool
  • rememberDevice(Authenticatable $user, ?int $lifetimeDays = null, ?string $deviceName = null): array returns ['token','cookie']
  • getRememberCookieName(): string
  • getRememberTokenFromRequest(Request $request): ?string
  • shouldSkipVerification(Authenticatable $user, ?string $token): bool
  • makeRememberCookie(string $token, ?int $lifetimeDays = null): Cookie
  • forgetRememberedDevice(Authenticatable $user, string $token): int
  • Recovery codes:
  • generateRecoveryCodes(Authenticatable $user, ?int $count = null, ?int $length = null, bool $replaceExisting = true): array returns plaintext codes
  • verifyRecoveryCode(Authenticatable $user, string $code): bool
  • getRemainingRecoveryCodesCount(Authenticatable $user): int
  • clearRecoveryCodes(Authenticatable $user): int

Custom Channel Classes

Configuration-Based Custom Channels

You can extend the built-in Email and SMS channels by configuring custom channel classes:

Programmatic Channel Registration

Challenge Generation Without Sending

Generate challenge codes without automatic delivery:

Creating a Custom MFA Channel

Steps

1. Implement CodingLibs\MFA\Contracts\MfaChannel with a unique getName() and a send(...) method
2. Register your channel during app boot (e.g., in a service provider) via MFA::registerChannel(...)
3. Issue a challenge using the new channel name: MFA::issueChallenge($user, 'your-channel')

Notes

• SMS driver defaults to log. Integrate your provider by implementing a custom channel or enhancing SmsChannel in your app via service container bindings.
• TOTP secret is stored encrypted by default via Eloquent cast.
• QR code generation requires either Imagick or GD PHP extensions. If neither is available, generation will throw a runtime exception.