Skip to main content
Most authentication packages collapse “who you are” and “who you’re acting as” into a single user object. Laravel Authentication separates them. It gives your Laravel application a stateless authentication layer built around five distinct concepts — Identity, Principal, Device, Tenant, and Type — all exposed through the standard Auth facade with no new API to learn. You keep Auth::check(), Auth::user(), standard middleware, and standard events; the package adds contextual accessors and ships hardened jwt and basic guards on top.

​
Why contextual auth

A single-model approach works fine for simple apps, but breaks down when the same person needs to act on behalf of different tenants, memberships, or roles — or when you need to track which client device issued a request for replay protection and last-seen tracking. By separating Identity from Principal, you can model the full “logged in as X, acting as Y inside tenant Z” relationship cleanly, and the package’s JWT pipeline encodes that context directly into the token claims.

​
Core concepts

ConceptWhat it is
IdentityWho logged in. The account behind the request — a person or a service account.
PrincipalWho the request is acting as. Often the same as the identity; can be a role or membership.
DeviceWhich client obtained the login — a browser, a mobile app, a CLI session.
TenantThe isolation boundary the principal acts within. Optional, for multi-tenant apps.
TypeAn optional categorical label on the tenant — e.g. "staff" vs "customer".

​
Adoption modes

The package supports two adoption shapes with the same guards, so you can start simple and grow without re-platforming. 2D mode (identity is the principal) is the simplest shape. One model implements both Identity and Principal. The user who logs in is the actor on whose behalf the request runs. Auth::identity() and Auth::principal() return the same object. 3D mode (identity → principal → tenant) is for multi-tenant apps where the logged-in human operates on behalf of a tenant-scoped actor. The identity and principal are separate models. A pid claim in the JWT encodes which principal is active, and Auth::principal() returns that tenant-scoped membership or role. Auth::tenant() returns the tenant the principal belongs to.

​
Guards

Two sessionless guards are included, registered via auth.guards.*.driver in config/auth.php:
  • jwt — Bearer token guard. Access tokens are self-verifying JWTs. The guard rehydrates identity and principal on every bearer request with no server-side access-token store. Refresh-token rotation is device-backed and stateful.
  • basic — HTTP Basic guard. Wraps credential validation in a constant-time Timebox to prevent timing side-channels. Supports per-guard identifier fields (email, username, key_id, etc.).

​
Contextual accessors

Import the package’s Auth facade to get IDE-friendly autocompletion on the contextual methods: 
use SineMacula\Laravel\Authentication\Facades\Auth;

Auth::check();       // bool         — standard Laravel
Auth::user();        // Identity|null — standard Laravel

Auth::identity();    // Identity|null  — the authenticated subject
Auth::principal();   // Principal|null — the acting principal
Auth::device();      // Device|null    — the issuing device
Auth::tenant();      // Tenant|null    — the tenant the principal acts within
Auth::type();        // string|null    — the tenant's type, when HasType is implemented
Both facades resolve through the same auth container key. You can keep the Illuminate facade for Auth::check() and Auth::user() — the contextual accessors only become available when you swap to the package facade.

​
Requirements

  • PHP ^8.3 (extensions: hash, mbstring, openssl)
  • Laravel ^12.40 || ^13.3

Installation

Install via Composer, publish config and migrations, and set your JWT secret.

Quick start

Wire up your first JWT guard and issue your first access token.