Laravel Auth

Premium, headless Laravel authentication hardening library for TOTP 2FA, passkeys, recovery codes, multi-channel OTP, trusted devices, and social authentication.

Headless Laravel authentication hardening with:

• TOTP 2FA
• recovery codes
• passkeys via WebAuthn
• email, SMS, and WhatsApp OTP
• trusted devices
• Socialite-based social account linking
• runtime tenant OAuth credentials for social login

This package does not replace your login system. It adds security layers on top of your existing auth flow.

Requirements

• PHP 8.2+
• Laravel 10, 11, 12, or 13
• database access for package tables
• HTTPS for browser passkey flows
• laravel/socialite support for social login helpers

Installation

Force republishing if you want to overwrite previously published files:

What ghost:laravel-auth publishes:

• config/laravel-auth.php
• one package migration file
• package OTP views to resources/views/vendor/laravel-auth
• SMS and WhatsApp transport stubs to app/LaravelAuth

Publish only OTP assets later if needed:

Local Package Development

To test this package from another Laravel app through a local path repository:

Then in the app:

If the app does not pick up local changes automatically:

What The Package Adds

Middleware aliases:

• 2fa
• laravel-auth.2fa
• laravel-auth.enforce
• laravel-auth.throttle

Published config:

• config/laravel-auth.php

Main facade contract:

• src/Contracts/LaravelAuthManager.php

Single package migration:

• database/migrations/2026_04_12_000001_create_laravel_auth_schema.php

Database objects created:

• user table columns:
  • laravel_auth_totp_secret
  • laravel_auth_two_factor_enabled
  • laravel_auth_confirmed_at
• laravel_auth_recovery_codes
• laravel_auth_trusted_devices
• laravel_auth_passkeys
• laravel_auth_webauthn_challenges
• laravel_auth_social_accounts
• laravel_auth_otp_challenges

Current Defaults

From the package config:

• enforce_2fa is true
• 2FA enforcement is pushed into the web middleware group
• OTP TTL is 300 seconds
• OTP max attempts is 5
• rate limit decay is 60 seconds
• TOTP uses 6 digits, 30-second period, 1-step window
• trusted devices are bound to user agent by default
• trusted-device IP binding is off by default
• WhatsApp OTP is disabled by default
• social runtime stateless mode defaults to false

Recommended Base Route Protection

Add throttling to sensitive verification endpoints:

TOTP 2FA Setup

Enable 2FA for a user:

Confirm setup:

Disable 2FA:

Demo 2FA Controller

Verifying 2FA During Login

TOTP or recovery code:

You can also verify without fully marking the session:

Recovery Codes

Generate or regenerate recovery codes:

Recovery codes are consumed automatically when passed through verifyOTP() or attemptOtp().

Passkeys / WebAuthn

Begin passkey registration:

Finish registration:

Begin assertion:

Verify assertion only:

Attempt assertion and fully authenticate:

OTP Channels

Email OTP

Send:

Verify only:

Attempt and mark session:

SMS OTP

Send:

Verify:

Attempt:

WhatsApp OTP

Enable it first in config/laravel-auth.php or your published config.

Send:

Verify:

Attempt:

Demo OTP Controller

Trusted Devices

Trusted devices are created automatically when you use:

• attemptOtp(..., rememberDevice: true, ...)
• attemptPasskey(..., rememberDevice: true, ...)

Relevant config keys:

• trusted_devices.cookie
• trusted_devices.ttl_days
• trusted_devices.bind_user_agent
• trusted_devices.bind_ip

Social Login

LaravelAuth supports two social-login modes:

1. static/global provider config
2. runtime provider config for tenant-specific OAuth credentials

Backward compatibility is preserved. Existing static Socialite-based setups continue to work.

Static Social Login Setup

Enable providers in your published config/laravel-auth.php.

Example:

Discover configured providers:

Redirect:

Callback:

Link:

Find local user:

List linked accounts:

Unlink:

Demo Static Social Controller

Runtime Tenant Social Login

Use runtime config when each tenant stores its own OAuth credentials.

Supported runtime keys:

• client_id
• client_secret
• redirect
• scopes
• with
• stateless

Tenant provider discovery:

Named-parameter redirect:

Positional redirect:

Named-parameter callback resolution:

Positional callback resolution:

Demo Tenant Social Controller

Suggested routes:

Suggested tenant credential table in your app:

Important Tenant Limitation

Runtime tenant credentials are supported, but linked social identities are still globally unique by:

• provider
• provider_user_id

That means the same Google or GitHub identity cannot currently be linked separately in multiple tenants through the package table.

Current package fit:

• good for tenant-specific OAuth credentials
• good for integer, UUID, ULID, or string-like local user IDs
• good when social identity should remain globally unique across the whole app

Not yet built into the package:

• tenant-scoped uniqueness for laravel_auth_social_accounts
• tenant-aware social account lookup columns like tenant_type / tenant_id

Session State Helpers

Enforce manually if needed:

Rate Limiting Helpers

Buckets used by the package:

• otp
• passkey

Strict Preset

Apply the built-in strict preset:

This tightens:

• enforced 2FA
• OTP TTL and max attempts
• passkey throttle settings
• trusted-device IP binding
• WebAuthn verification requirements

OTP Provider Configuration

Mail

Enabled by default.

Relevant config:

• otp_channels.email.enabled
• otp_channels.email.view
• otp_channels.email.subject

SMS providers

Supported built-ins:

• Twilio
• Vonage
• MessageBird
• MSG91
• custom

Set the provider in config:

WhatsApp providers

Supported built-ins:

• Twilio
• custom

WhatsApp is disabled by default. Enable it in your published config before use.

Custom transports

Publish stubs:

Then wire your own classes in the published config:

Troubleshooting

2FA required unexpectedly

• confirm the user session completed a second factor
• confirm the verification endpoint calls an attempt* method
• confirm the trusted-device cookie still matches the request

Passkey challenge invalid or expired

• send challenge_id back from the frontend
• do not reuse the same challenge
• confirm RP ID matches the real app hostname

Social provider missing

• confirm the provider is enabled in laravel-auth.social.providers
• confirm static config has client_id, client_secret, and redirect
• for runtime config, confirm client_id and client_secret are present
• if runtime config omits redirect, make sure a fallback redirect exists in laravel-auth.social.providers.{provider}.redirect

Runtime config named parameter error in IDE

If your app or IDE says Unknown named parameter $runtimeConfig, refresh the package in the app:

Or use positional arguments:

OTP verification keeps failing

• confirm destination matches the original challenge destination
• confirm provider credentials and sender configuration
• confirm the code is not expired
• confirm the attempt bucket is not rate limited

Testing & Quality Control

To run the automated test suite and ensure all quality gates pass, use the following commands:

Public API Reference

2FA / TOTP / Recovery

Passkeys

OTP Channels

Social Helpers

State / Enforcement / Utility

License

The MIT License (MIT). Please see License File for more information.