README

Auth for Laravel

Headless, multi-guard account authentication for Laravel: password, magic-link, email-code and passkey login, a challenge engine for two-factor and forced enrolment, RS256 access tokens with rotating refresh tokens and device sessions, registration, invitations, email verification, password resets and a login-activity log — with an event for every state change and opt-in JSON endpoints. It owns the policy and orchestration; tokens, sessions, TOTP, WebAuthn and crypto come from the roundly security packages it builds on.

Installation

Requires PHP 8.4 (ext-bcmath, ext-mbstring, ext-openssl), Laravel 12 or 13, a cache store with atomic locks, and a mail transport.

composer require roundly-consulting/auth-for-laravel
php artisan jwt:generate-keys
php artisan authentication:install   # publishes config + migrations, prints the guard wiring
php artisan migrate

Wire each guard the way authentication:install prints it — a jwt guard with its own audience and the authentication user provider in config/auth.php, plus RoundlyConsulting\Auth\Support\TokenVersionResolver as jwt.guard.token_version (without it, invalidation revokes nothing). php artisan authentication:check confirms the setup.

Usage

Give the guard's model the contracts of the features it uses:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use RoundlyConsulting\Auth\Concerns\HasAuthentication;
use RoundlyConsulting\Auth\Contracts\Account;
use RoundlyConsulting\Passkeys\Concerns\InteractsWithPasskeys;
use RoundlyConsulting\Passkeys\Contracts\HasPasskeys;
use RoundlyConsulting\RefreshTokens\Traits\HasRefreshTokens;
use RoundlyConsulting\TwoFactor\Concerns\HasTwoFactorAuthentication;
use RoundlyConsulting\TwoFactor\Contracts\TwoFactorAuthenticatable;

class User extends Authenticatable implements Account, HasPasskeys, TwoFactorAuthenticatable
{
    use HasAuthentication, HasRefreshTokens, HasTwoFactorAuthentication, InteractsWithPasskeys, Notifiable;

    protected function casts(): array
    {
        return [...$this->authenticationCasts(), ...$this->twoFactorCasts(), 'email_verified_at' => 'datetime'];
    }
}

use RoundlyConsulting\Auth\DataTransferObjects\PasswordCredentials;
use RoundlyConsulting\Auth\Facades\Authentication;
use RoundlyConsulting\Auth\Http\Resources\ChallengeResource;
use RoundlyConsulting\Auth\Http\Resources\TokenPairResource;

$guard = Authentication::guard('users');

$result = $guard->attempt(
    new PasswordCredentials(identifier: $request->string('email')->toString(), password: $request->string('password')->toString()),
    $guard->contextFrom($request),
);

return $result->isAuthenticated()
    ? TokenPairResource::make($result->tokens)
    : ChallengeResource::make($result->challenge);   // continue with $guard->challenges()->complete(…)

Rotate the refresh token, or sign the account out of every device:

$tokens = $guard->refresh($refreshToken, $guard->contextFrom($request));   // the old access token stops working

$guard->logoutEverywhere($user);

Documentation

The full documentation — configuration, every feature and its API, and testing — lives on our website: roundly-consulting.com/open-source/docs/auth-for-laravel

Release notes are in CHANGELOG.md. To contribute, see the contributing guide.

Support our work

This package is free and open source, built and maintained by Roundly Consulting. If it saves you time, please consider supporting our open-source work — a one-time donation, a monthly pledge on Patreon or a crypto donation helps fund maintenance, new features and new packages.

License

The MIT License (MIT). See LICENSE.md.

roundly-consulting / auth-for-laravel

Package info

Security

Fund package maintenance!

Statistics