Search by

sinemacula / laravel-authentication

sinemacula

Stateless contextual authentication primitives (Identity, Principal, Session, Tenant) for Laravel 12 and 13.

Package info

github.com/sinemacula/laravel-authentication

pkg:composer/sinemacula/laravel-authentication

Statistics

Installs: 5 409

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 7

dev-master 2026-11-20 03:37 UTC

This package is auto-updated.

Last update: 2026-11-20 03:38:33 UTC


README

Latest Stable Version PHP Version Laravel Version Build Status Quality Gates Maintainability Code Coverage Total Downloads License

Stateless contextual authentication for Laravel. It tells apart the Identity that signed in, the Principal it acts as and the Session it signed in on, through Laravel's own Auth facade, middleware and events, and adds contextual accessors (Auth::identity(), Auth::principal(), Auth::tenant(), Auth::session()) and a JWT guard.

It signs in by password, one-time code, passkey or a trusted external identity provider; holds a session pending while it owes a further factor or a choice of principal; judges step-up and freshness against the session's proofs; issues API keys and client credentials to machines; and revokes sessions on every security change. It provides services and helpers, not routes: each action is one method taking plain values, and your application owns its endpoints and payloads. MFA, authorisation, SSO and audit packages plug into its extension points.

Core Concept

Concept What it is
Identity Who logged in. The account behind the request - a person or a service account.
Principal Who the request is acting as. Often the same as the identity; else a membership of a tenant, or a platform principal.
Session One sign-in, on one application, on one device: a browser, a mobile app, a CLI. Refresh and revocation live here.
Tenant The isolation boundary a principal belongs to; a session acts in one, its active tenant (Auth::tenant()). Optional.
Application The app being signed into, e.g. admin, console, mobile. Each application is a guard with its own methods and lifetimes.

Start 2D (the identity is the principal) and grow into 3D (identity -> principal -> tenant) without changing guards. Access tokens are self-verifying JWTs; refresh is stateful, held per session, so replays and revoked sessions are caught on the server.

Installation

composer require sinemacula/laravel-authentication

Configuration

Publish the config and the migrations, migrate, generate a signing key, and name the issuer and audience every token carries (a guard without them fails closed):

php artisan vendor:publish --tag=authentication-config
php artisan vendor:publish --tag=authentication-migrations
php artisan migrate

echo "AUTHENTICATION_JWT_KEY=$(openssl rand -base64 48)" >> .env
echo "AUTHENTICATION_JWT_ISSUER=https://auth.example.com" >> .env
echo "AUTHENTICATION_JWT_AUDIENCE=https://api.example.com" >> .env

Register a jwt guard and a model provider in config/auth.php. Each guard is an application, and allows only the sign-in methods it lists:

'guards' => [
    'api' => [
        'driver'      => 'jwt',
        'provider'    => 'users',
        'application' => ['methods' => ['password']],
    ],
],

'providers' => [
    'users' => [
        'driver' => 'model',
        'model'  => App\Models\AppUser::class,
    ],
],

See Installation for keys and providers, and Configuration for every option.

Usage

Give your user model the contracts and traits:

namespace App\Models;

use Illuminate\Database\Eloquent\Relations\MorphMany;
use Illuminate\Foundation\Auth\User;
use SineMacula\Laravel\Authentication\Concerns\ActsAsPrincipal;
use SineMacula\Laravel\Authentication\Concerns\Authenticatable;
use SineMacula\Laravel\Authentication\Contracts\HasSessions;
use SineMacula\Laravel\Authentication\Contracts\Identity;
use SineMacula\Laravel\Authentication\Contracts\Principal;
use SineMacula\Laravel\Authentication\Models\Session;

class AppUser extends User implements Identity, Principal, HasSessions
{
    use Authenticatable, ActsAsPrincipal;

    public function sessions(): MorphMany
    {
        return $this->morphMany(Session::class, 'authenticatable');
    }
}

Sign in through the guard's session service, and protect routes as with any Laravel guard:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use SineMacula\Laravel\Authentication\Facades\Auth;
use SineMacula\Laravel\Authentication\Secrets\SecretResponse;
use SineMacula\Laravel\Authentication\Sessions\SignInContext;

Route::post('/login', function (Request $request) {
    $credentials = $request->validate([
        'email'    => ['required', 'string'],
        'password' => ['required', 'string'],
    ]);

    $result = Auth::sessions('api')->signIn('password', $credentials, SignInContext::fromRequest($request));

    abort_unless($result->isSignedIn(), 401);

    // The tokens are secrets: SecretResponse reveals them into the body and marks it not to be stored.
    return SecretResponse::json([
        'access_token'  => $result->session->tokens->accessToken,
        'expires_in'    => $result->session->tokens->expiresIn,
        'refresh_token' => $result->session->tokens->refreshToken,
    ]);
});

Route::middleware('auth:api')->get('/me', fn () => Auth::identity());

Guides

Guide Covers
Installation Keys, guards and providers, the 401, localisation, access-only mode
Identity models 2D and 3D models, identifiers, verification, activity
Signing in The session service, pending sessions, one-time codes, passkeys, custom methods, factors
Refreshing Refresh, the refresh cookie, what a refresh judges and replay detection
Sessions Proofs, step-up, reauthentication, freshness, switching, signing out, listing sessions, revocation, the caller
Passwords Password policy, setting a password and password reset
Changing identifiers Changing an email address or phone number
Machine credentials Non-human identities, scopes, API keys and client credentials
Events Every event, its context and the failure outcomes
Configuration Every configuration key
Operations Read replicas, Octane, key rotation, pruning and the configuration check
Testing Acting as an identity in your tests, context assertions and fakes
Extending Extension points and the MFA, authorisation, SSO and audit seams

The security and lifecycle contracts behind them, for maintainers and reviewers, are in docs/design.

Requirements

  • PHP ^8.3 (extensions: hash, mbstring, openssl; sodium, bundled with PHP, for EdDSA passkeys)
  • Laravel ^12.40 || ^13.3

Testing

composer test               # all suites in parallel (Paratest)
composer test:coverage      # all suites with clover coverage
composer test:unit          # unit suite only
composer test:feature       # feature suite only
composer test:integration   # integration suite only
composer test:performance   # performance budget suite (serial)
composer test:mutation      # scoped mutation gate
composer test:mutation:full # full mutation suite (no thresholds)
composer bench              # PHPBench hot-path benchmarks
composer check              # static analysis + style
composer format             # format the codebase
composer smells             # advisory code smells (duplication, complexity)

Changelog

See CHANGELOG.md for a list of notable changes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branching, commits, code quality, and pull requests.

Security

If you discover a security vulnerability, please report it responsibly. See SECURITY.md for the disclosure policy and contact details.

License

Licensed under the Apache License, Version 2.0.