sinemacula / laravel-authentication
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
Requires
- php: ^8.3
- ext-hash: *
- ext-mbstring: *
- ext-openssl: *
- firebase/php-jwt: ^7.0
- laravel/framework: ^12.40|^13.3
- web-auth/webauthn-lib: ^5.3
Requires (Dev)
- brianium/paratest: ^7.20
- doctrine/coding-standard: ^14.0
- friendsofphp/php-cs-fixer: ^3.95.19
- infection/infection: ^0.33.2
- larastan/larastan: ^3.9
- laravel/octane: ^2.24
- mockery/mockery: ^1.6
- orchestra/testbench: ^10.2|^11.0
- phpbench/phpbench: ^1.6.1
- phpstan/extension-installer: ^1.4
- phpstan/phpdoc-parser: ^2.3
- phpstan/phpstan: ^2.1
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-mockery: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpstan/phpstan-strict-rules: ^2.0
- phpunit/phpunit: ^12.5
- sinemacula/coding-standards-laravel: ^1.7.1
- slevomat/coding-standard: ^8.28
- squizlabs/php_codesniffer: ^3.13.6 || ^4.0.2
Suggests
- giggsey/libphonenumber-for-php: Required to accept mobile or free-form phone numbers for one-time codes: back an identifier normaliser registered as `phone` with it (the shipped one accepts only E.164).
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 03:38:33 UTC
README
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.