Spôsoby prihlásenia

Štyri primárne spôsoby, každý zapínateľný pre konkrétny guard. Aspoň jeden musí byť zapnutý:

'guards' => [
    'users' => [
        'model' => App\Models\User::class,
        'login' => [
            'password' => true,
            'magic_link' => true,
            'email_otp' => true,
            'passkey' => true,               // passwordless
            'reveal_account_state' => true,  // disabled/unverified codes only after a verified first factor
        ],
        'magic_link' => ['ttl' => 900, 'same_device' => false],
        'email_otp' => ['ttl' => 600, 'length' => 6, 'max_attempts' => 5],
    ],
],

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

// Password
$result = $guard->attempt(new PasswordCredentials('[email protected]', $password), $context);

// Magic link: the request never reveals whether the address exists
$guard->requestMagicLink('[email protected]', $context);
$result = $guard->consumeMagicLink($token, $context);

// Email code
$guard->requestEmailOtp('[email protected]', $context);
$result = $guard->verifyEmailOtp('[email protected]', $code, $context);

// Passwordless passkey (discoverable credentials)
$options = $guard->passkeyLoginOptions($context);             // for navigator.credentials.get()
$result  = $guard->loginWithPasskey($assertion, $context);    // passkeys' AuthenticationResponseData

Heslo

Limity login, login_ip a login_account sa overia ešte pred hašovaním. Neznáme účty a účty bez hesla sa overujú voči fiktívnemu hashu s rovnakou náročnosťou, takže čas odpovede neprezradí, či účet existuje. Neúspech zaťaží všetky tri limity, zvýši voliteľné počítadlo uzamknutia a vráti invalid_credentials. Tvrdo uzamknutý účet odpovie presne ako pri nesprávnom hesle — fiktívna kontrola, pokus zostane započítaný, invalid_credentials — takže zámok neprezradí heslo ani to, že účet existuje; po zahašovaní hesla sa locked_until načíta znova, takže zámok zapísaný medzitým toto prihlásenie odmietne rovnako, aj so správnym heslom. Správne heslo dostane pokus späť, až keď prihlásenie prejde do výzvy alebo sa dokončí: ak prihlásenie takéto heslo potom odmietne jednotným invalid_credentials (deaktivovaný či neoverený účet bez reveal_account_state, jednotné zamietnutie pre riziko, nedostupné dodatočné overenie), pokus zostane započítaný ako pri nesprávnom hesle, takže limit správny tip neprezradí.

Magic link

Skutočný aktívny účet dostane 64-znakový odkaz s tajomstvom vo fragmente URL; požiadavka vždy odpovie 202 sent. Pri použití musí adresa odkazu stále patriť účtu. S magic_link.same_device sa pred uplatnením overí odtlačok žiadajúceho zariadenia, takže nezhoda odkaz nespotrebuje.

E-mailový kód

Rovnaká logika žiadosti ako pri magic linku. Overenie prechádza tromi prihlasovacími limitmi (hádanie kódu je pokus o prihlásenie), nikdy neprezradí attempts_left a viaže kód na jeho adresu.

Passkey

Options sú discoverable — bez identifikátora a bez allowCredentials. S passkeys.satisfies_mfa vyžadujú overenie používateľa, vynútené pre daný ceremoniál. Id ceremoniálu sa musí vrátiť spolu s assertion, credential iného guardu sa odmietne a každý neúspech je jednotné invalid_credentials.

Čím prejde každé prihlásenie

• Dôsledky vlastníctva — prihlásenie magic linkom alebo e-mailovým kódom overí adresu (verification.verify_on_email_login); pri verification.secure_on_email_login toto prvé overenie zároveň odoberie účet tomu, kto adresu zaregistroval skôr než jej vlastník — pozri Prevzatie účtu nižšie.
• Stav účtu — deaktivovaný vráti account_disabled (alebo invalid_credentials pri vypnutom reveal_account_state); uzamknutý vráti too_many_attempts pri prihlásení odkazom, kódom či passkey (prihlásenie heslom už predtým vrátilo invalid_credentials); neoverený pri required_for_login vráti email_not_verified.
• Prehašovanie hesla.
• Doplnenie jazyka, ak ho účet nemá, a detekcia nového zariadenia.
• Riziko — nastavená reakcia môže upozorniť, vyžiadať druhý faktor alebo prihlásenie zamietnuť, a to pri akomkoľvek spôsobe prihlásenia.
• Potrebné kroky — dodatočné overenie bez faktora, ktorým by sa účet overil, sa zamietne. Až potom sa vynuluje počítadlo uzamknutia a vyčistí prihlasovací limit, takže jednotné odmietnutie pred týmto bodom ich nechá presne tak ako nesprávne heslo.
• Buď výzva, alebo úspešné dokončenie: tokeny, last_login_at, aktivita, LoginSucceeded a TokensIssued.

Prevzatie účtu

Predčasné prevzatie účtu (pre-hijacking): niekto zaregistruje adresu, ktorá mu nepatrí, nastaví heslo a ponechá si reláciu — alebo si nastaví TOTP či passkey. Keď sa vlastník adresy neskôr prihlási magic linkom alebo e-mailovým kódom, toto prihlásenie dokazuje vlastníctvo schránky, nikdy nie heslo, a predchádzajúce prihlasovacie údaje predvolene zostávajú platné. Pri verification.secure_on_email_login = true (voliteľné, pre každý guard) e-mailové prihlásenie, ktoré overí neoverenú adresu, v jednej transakcii odstráni:

• heslo a password_changed_at — null, alebo prázdny reťazec, ak je stĺpec NOT NULL; oboje znamená bez hesla a žiadny hash sa nikdy nezhoduje;
• nastavenie dvojfaktora, potvrdené aj čakajúce;
• všetky passkeys, ak passkeys.mode guardu nie je off;
• všetky relácie a refresh tokeny, čakajúce výzvy a jednorazové tajomstvá prihlasovacích údajov (odkazy na obnovu, odkazy a kódy na prihlásenie, čakajúce zmeny e-mailu) — invalidácia security, vždy all. Pár tokenov aktuálneho prihlásenia sa vydá až potom, takže vlastník zostane prihlásený.

Potom sa spustí AccountClaimed. Vlastník si heslo či faktory nastaví znova zo svojej relácie — nastavenie hesla predvolene vyžaduje nedávne opätovné overenie a čerstvé e-mailové prihlásenie sa započíta:

use Illuminate\Support\Facades\Event;
use RoundlyConsulting\Auth\Events\AccountClaimed;

Event::listen(function (AccountClaimed $event): void {
    $event->method;            // the email login that proved the address (LoginMethod)
    $event->passwordRemoved;   // bool
    $event->twoFactorRemoved;  // bool
    $event->passkeysRemoved;   // int
    $event->sessionsRevoked;   // int
});

Je to bezpečné pri súbehu: overenie sa uplatní podmieneným updatom v tej istej transakcii, takže z dvoch súbežných e-mailových prihlásení účet zabezpečí len jedno a o tom, čo odstrániť, sa rozhoduje podľa riadku načítaného znova v tejto transakcii. Prihlásenie heslom, ktoré načítalo účet ešte pred prevzatím, vydá pár pod starou verziou tokenu: jeho prístupový token sa odmietne a jeho rodina refresh tokenov sa zruší pri prvej obnove.

Nespustí sa pri overovacom odkaze či kóde (vlastný krok registrujúceho po registrácii s heslom), pri prihlásení heslom, obnove hesla (tá heslo nahradí a všetky relácie aj tak ukončí), pozvánke (tá vždy vytvorí nový účet) ani pri už overenej adrese. Pri verify_on_email_login = false e-mailové prihlásenie adresu neoverí a nič sa neodstráni — authentication:check na to upozorní.

Referencie metód overenia

Prístupové tokeny nesú amr (RFC 8176). Dokončená výzva pridá svoje faktory a mfa: