Prihlasovacie výzvy

Keď sa prvý faktor overí, no treba viac, výsledkom je výzva: nepriehľadný token (ukladá sa len jeho HMAC), zostávajúce kroky a počet zostávajúcich pokusov. Kroky sa dokončujú v poradí; overovacie kroky sú vždy pred krokmi nastavenia:

POST /users/auth/login
{ "identifier": "[email protected]", "password": "…" }

200 { "status": "challenge", "challenge_token": "…", "expires_at": "…", "attempts_left": 5, "method": "password",
      "completed": [], "remaining": [ { "step": "second_factor", "methods": ["totp", "recovery_code", "passkey"] } ] }

POST /users/auth/challenge/two-factor
{ "challenge_token": "…", "code": "123456" }

200 { "status": "authenticated", "token_type": "Bearer", "access_token": "eyJ…", "refresh_token": "…", "session_id": "0199…" }

Kroky

Ktoré kroky prihlásenie potrebuje

Závisí to od 2FA režimu guardu, režimu passkeys a pravidla passkey ako druhého faktora, od toho, čo má účet nastavené, a od reakcie na riziko:

• Primárne passkey — nastavené TOTP sa vyžaduje, len ak je satisfies_mfa vypnuté; pri two_factor.mode = required bez TOTP sa nastavenie vynúti, ak je satisfies_mfa vypnuté alebo required_with_passkey zapnuté.
• E-mailové spôsoby (magic link, e-mailový kód, pozvánka) preskočia pravidlá dvojfaktora, ak je two_factor.after_email_login false. Obnova hesla nikdy nie je výnimkou a rovnako ani registrácia (nepreukazuje vlastníctvo schránky).
• Nastavené TOTP znamená krok second_factor (TOTP, záložný kód a passkey pri second_factor = allowed).
• passkeys.second_factor = required (alebo required_when_enrolled pri existujúcom passkey) pridá krok passkey — alebo registráciu passkey, ak ho účet nemá.
• two_factor.mode = required bez TOTP vynúti nastavenie — alebo prijme passkey účtu ako druhý faktor pri second_factor = allowed a zapnutom passkey_satisfies_required; passkeys.mode = required bez passkey vynúti registráciu passkey.
• Reakcia na riziko require_second_factor pridá na začiatok krok druhého faktora, alebo prihlásenie zamietne, ak ho účet nemá. Platí pre každý spôsob prihlásenia — after_email_login = false vyníma e-mailové prihlásenia z pravidiel dvojfaktora, nikdy nie z dodatočného overenia. Prihlásenie passkey, ktoré sa počíta ako MFA (satisfies_mfa), už dodatočným overením je; inak sa ráta len TOTP alebo záložný kód, a ak ich účet nemá, prihlásenie sa zamietne.

Konfigurácia

'challenge' => [
    'ttl' => 300,
    'enrolment_ttl' => 900,
    'max_attempts' => 5,
    'allow_enrolment' => true,
    'enrolment_requires_verified_email' => true,
    'bind' => ['user_agent' => true, 'ip' => false, 'device_header' => true],
    'max_active_per_account' => 3,   // older active challenges are superseded
],

'two_factor' => [
    'mode' => env('AUTHENTICATION_TWO_FACTOR', 'optional'),  // off|optional|required
    'after_email_login' => true,          // magic link / email OTP / invitation also need the 2nd factor
    'required_with_passkey' => false,     // passkey primary still forces TOTP enrolment when mode=required
    'passkey_satisfies_required' => true, // a passkey second factor satisfies mode=required (false ⇒ TOTP also required)
],

'passkeys' => [
    'mode' => env('AUTHENTICATION_PASSKEYS', 'optional'),    // off|optional|required
    'second_factor' => 'allowed',        // off|allowed|required_when_enrolled|required
    'satisfies_mfa' => true,             // a UV passkey login needs no further factor
],

Životný cyklus a bezpečnosť

• Viazanie na zariadenie — odtlačok z user agenta, IP a X-Device-Id podľa challenge.bind (IP predvolene vypnutá: mobilní klienti menia sieť počas prihlásenia), porovnávaný v konštantnom čase.
• Pokusy — kód TOTP, záložný kód aj kód na potvrdenie nastavenia si pokus atomicky započíta ešte pred overením, takže súbežné hádanie nikdy neoverí viac kódov, než dovoľuje max_attempts; platný kód pokus vráti. Passkey assertion sa započíta len pri neúspechu. Pri max_attempts sa výzva zneplatní a odpoveď obsahuje attempts_left.
• Nahradenie — aktívnych zostane najviac max_active_per_account výziev; staršie sa nahradia.
• Jednorazovosť — kroky postupujú s optimistickou kontrolou verzie; dokončenie znova overí stav účtu aj snímku verzie tokenu, takže obnova hesla, deaktivácia či odhlásenie všade medzitým prihlásenie zruší.
• Invalidácia — každá invalidácia s rozsahom iným ako none zneplatní aj aktívne výzvy účtu.

Nastavenie faktora vo výzve

Vynútené nastavenie vyžaduje challenge.allow_enrolment a — pri enrolment_requires_verified_email — overenú adresu; inak je odpoveďou enrolment_required (403). Opätovné spustenie nastavenia ho vydá znova bez započítania pokusu; nesprávne potvrdenie sa započíta. Potvrdenie TOTP spustí TwoFactorEnabled a ukončí ostatné relácie, samotnú výzvu však nie.