Fasáda Authentication

Všetko, čo robí HTTP vrstva, je dostupné aj z PHP cez RoundlyConsulting\Auth\Facades\Authentication (bez aliasu Auth — kolidoval by s Laravelom). Authentication::guard('clients') je API jedného guardu:

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('clients');

$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(…)

Každá ďalšia metóda fasády pre guard beží na predvolenom guarde (authentication.default), takže Authentication::twoFactor()->status($user) je to isté ako Authentication::guard()->twoFactor()->status($user):

use RoundlyConsulting\Auth\DataTransferObjects\InvitationData;
use RoundlyConsulting\Auth\Enums\InvalidationReason;
use RoundlyConsulting\Auth\Facades\Authentication;

// Every per-guard method runs on the default guard (authentication.default)…
Authentication::twoFactor()->status($user);          // enabled, pending, recovery codes left, mode
Authentication::passwords()->set($user, 'n3w-Passphrase!', InvalidationReason::Security);
Authentication::invitations()->create(new InvitationData('[email protected]'))->url;   // needs invitations.enabled
Authentication::lock($user, seconds: 3600);

// …or on a named guard
Authentication::guard('clients')->twoFactor()->status($client);

// Manager-level
Authentication::guards();                            // ['users', 'clients']
Authentication::prune(days: 30);                     // PruneReport — what authentication:prune runs

Pozvánky sú predvolene vypnuté: kým guard nenastaví invitations.enabled = true, každé volanie invitations() vyhodí LoginMethodDisabled (cez HTTP 404 method_disabled).

Základné operácie

Authentication::guard($name) vráti GuardContext; každá metóda spustí jednu akciu z kontajnera pre daný guard:

Metóda	Vracia
`attempt(PasswordCredentials, SessionContext)`	LoginResult (tokeny alebo výzva)
`requestMagicLink($email, $ctx) / consumeMagicLink($token, $ctx)`	void / LoginResult
`requestEmailOtp($email, $ctx) / verifyEmailOtp($email, $code, $ctx)`	void / LoginResult
`passkeyLoginOptions($ctx) / loginWithPasskey($response, $ctx)`	RequestOptionsData / LoginResult
`register(RegistrationData)`	RegistrationResult
`issueTokens($account, $ctx, $method, $amr)`	TokenPair — prihlásenie, za ktoré ručí hostiteľ (impersonácia, SSO); spustí TokensIssued
`refresh($refreshToken, $ctx)`	TokenPair (predošlý prístupový token relácie prestane platiť)
`sessions($account, $currentSessionId)`	Collection<SessionData>
`logout($account, $current) / logoutSession($account, $id) / logoutOthers($account, $current) / logoutEverywhere($account)`	— / — / int / int
`invalidate($account, InvalidationReason, ?$keep, ?$ctx)`	?TokenPair (znovu vydaný pár pri others)
`disable($account, ?$reason) / enable($account)`	—
`lock($account, ?$seconds) / unlock($account)`	CarbonImmutable / — (zámok upozorní vlastníka, nikdy neodhlási)
`updateLocale($account, LocaleData)`	Account
`activity($account, $perPage = 20)`	Stránkovaná vlastná LoginActivity
`contextFrom(Request) / tokenFrom(Request)`	SessionContext / CurrentToken
`name() / config() / accounts()`	string / GuardConfig / AccountRepository

Podkontexty

Každá oblasť má vlastný podkontext — na guarde alebo na fasáde pre predvolený guard ($a je účet):

Podkontext	Metódy
`twoFactor()`	`status($a), start($a), confirm($a, $code, ?$current, ?$ctx), disable($a, ?$current, ?$ctx), regenerateRecoveryCodes($a, ?$current, ?$ctx)`
`passkeys()`	`all($a), registrationOptions($a), register($a, $response, ?$name, ?$current, ?$ctx), rename($a, Passkey\|int, $name), remove($a, Passkey\|int, ?$current, ?$ctx)`
`passwords()`	`set($a, $password, $reason), change($a, ChangePasswordData), requestReset($email, $ctx), reset(PasswordResetData), validate($password, ?$a, ?$email), rule(?$email)`
`email()`	`sendVerification($a, ?$ctx), requestVerification($a, $ctx), resendVerification($email, $ctx), verify($tokenOrCode, ?$email, $ctx), requestChange($a, EmailChangeData), confirmChange($token, $ctx)`
`invitations()`	`create(InvitationData) → InvitationLink, accept(AcceptInvitationData) → RegistrationResult, paginate(?$status, $perPage), preview($token), find($id), resend(Invitation\|int), revoke(Invitation\|int), link(Invitation\|int)`
`reauthentication()`	`methods($a), sendCode($a, $ctx), passkeyOptions($a, $current), confirm($a, ReauthenticationData), ensureRecent($a, $current, ?$seconds), ensureFor(SensitiveAction, $a, $current)`
`challenges()`	`complete(ChallengeFactorData), passkeyOptions($token, $ctx), passkeyEnrolmentOptions($token, $ctx), startTwoFactorEnrolment($token, $ctx)`

K tomu Authentication::prune(?$days), guards(), routes($guard) a currentGuard().

Rozsah

Každá metóda, ktorá prijíma účet, odmietne model iného guardu (AuthenticationMisconfigured, „belongs to another guard“) skôr, než čokoľvek zapíše. Pozvánka či token výzvy iného guardu a passkey iného účtu sú neznáme (InvitationNotFound, ChallengeInvalid, PasskeyNotFound).

Konanie za prihláseného používateľa

Pri zmenách prihlasovacích údajov odovzdajte ako $current token volajúceho ($guard->tokenFrom($request)): jeho zariadenie sa pri others zachová a vráti sa znovu vydaný pár — klient naň musí prejsť. Pri volaniach z administrácie a CLI $current vynechajte. HTTP vrstva navyše pred akciami z reauthentication.required_for vyžaduje nedávne opätovné overenie; volajúci z PHP za používateľa ručia sami, alebo najprv spustia tú istú bránu:

use RoundlyConsulting\Auth\Enums\SensitiveAction;
use RoundlyConsulting\Auth\Facades\Authentication;

$guard   = Authentication::guard('users');
$current = $guard->tokenFrom($request);

$guard->reauthentication()->ensureFor(SensitiveAction::DisableTwoFactor, $user, $current);
$tokens = $guard->twoFactor()->disable($user, $current, $guard->contextFrom($request));   // swap the client to $tokens

passwords()->change() spustí bránu sám pre účet, ktorý si nastavuje prvé heslo. Používajte Authentication::…, nie metódy modelov z nižších balíkov: $user->disableTwoFactor(), $user->regenerateTwoFactorRecoveryCodes(), Passkeys::for($user)->revoke(), $user->revokeAllSessions() či RefreshTokens::sessions($user)->revokeAll() zmenia prihlasovací údaj, no obídu pravidlá tohto balíka — režim guardu, invalidáciu, udalosti aj upozornenie vlastníka.

Vstupy z požiadavky

$guard->contextFrom($request) zachytí IP adresu, user agent, id zariadenia z hlavičky X-Device-Id, vstupy device_name a timezone a dohodnutý jazyk; pre joby a testy vytvorte SessionContext priamo: new SessionContext(ipAddress: '203.0.113.9', userAgent: 'CLI'). $guard->tokenFrom($request) načíta prístupový token volajúceho (jti, sid, auth_time, amr).

Spracovanie výsledku prihlásenia

LoginResult je buď prihlásený (TokenPair), alebo vyžaduje výzvu (PendingChallenge). Zostávajúce kroky dokončíte cez challenges()->complete():

use RoundlyConsulting\Auth\DataTransferObjects\ChallengeFactorData;
use RoundlyConsulting\Auth\DataTransferObjects\PasswordCredentials;
use RoundlyConsulting\Auth\Enums\FactorMethod;
use RoundlyConsulting\Auth\Facades\Authentication;

$guard   = Authentication::guard('users');
$context = $guard->contextFrom($request);

$result = $guard->attempt(new PasswordCredentials($request->input('identifier'), $request->input('password')), $context);

if ($result->requiresChallenge()) {
    $pending = $result->challenge;   // token, expiresAt, method, completed, remaining (ChallengeRequirement[]), attemptsLeft
    // … later, with the user's TOTP code:
    $result = $guard->challenges()->complete(new ChallengeFactorData(
        challengeToken: $pending->token,
        method: FactorMethod::Totp,
        context: $context,
        code: $request->input('code'),
    ));
}

$tokens = $result->tokens;   // accessToken, accessExpiresAt, refreshToken, refreshExpiresAt, sessionId, accessTokenId, tokenType

Ak chcete z vlastného controllera odpovedať v JSON tvare balíka, použite LoginResponse:

use RoundlyConsulting\Auth\Http\Responses\LoginResponse;

// Render a LoginResult in the same shape as the package endpoints
return LoginResponse::make($result, $request);

Relácie riadené hostiteľom

issueTokens() vydá reláciu pre prihlásenie, za ktoré ručí váš kód — impersonácia, SSO callback, testy — a spustí TokensIssued:

use RoundlyConsulting\Auth\Enums\AuthMethodReference;
use RoundlyConsulting\Auth\Enums\InvalidationReason;
use RoundlyConsulting\Auth\Enums\LoginMethod;

// SSO callback: the host vouches for the authentication (fires TokensIssued)
$pair = Authentication::guard('users')->issueTokens($user, $context, LoginMethod::Host, [AuthMethodReference::Mfa]);

// Incident response
Authentication::guard('users')->invalidate($user, InvalidationReason::Security);
Authentication::guard('users')->disable($user, 'chargeback fraud');

Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

Ďalšie spôsoby podpory vrátane kryptomien

Odoslaním daru súhlasíte s našimi podmienkami prijímania darov.

Podporte našu open-source prácu Pridajte sa k nám na Patreone

Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

Ponuka do 48 hodín Prezrieť všetky balíky