Registrácia

Registrácia pridá prihlásenému používateľovi nový prístupový kľúč na dve volania handle účtu: pripravte možnosti pre prehliadač, potom overte jeho odpoveď a kľúč uložte. Voliteľný názov slúži ako popis na obrazovke „Vaše prístupové kľúče“:

use RoundlyConsulting\Passkeys\Facades\Passkeys;
use RoundlyConsulting\Passkeys\DataTransferObjects\RegistrationResponseData;

// 1. Server -> client: creation options (also stores a single-use challenge).
$options = Passkeys::for($user)->registrationOptions();
return response()->json($options); // feed publicKey to navigator.credentials.create()

// 2. Client -> server: verify the attestation response and persist the credential.
//    Pass an optional friendly name for a "your passkeys" screen.
$passkey = Passkeys::for($user)->register(
    RegistrationResponseData::fromArray($request->validated()),
    name: 'MacBook Touch ID',
);

Možnosti registrácie

registrationOptions() vracia CreationOptionsData. Objekt je JsonSerializable presne do tvaru, ktorý očakáva navigator.credentials.create({ publicKey }) — binárne položky v base64url a vedľa publicKey aj ceremonyId:

{
  "ceremonyId": "…40 chars…",
  "publicKey": {
    "rp":   { "id": "example.com", "name": "Example" },
    "user": { "id": "…b64url…", "name": "[email protected]", "displayName": "Jane Doe" },
    "challenge": "…b64url…",
    "pubKeyCredParams": [ { "type": "public-key", "alg": -7 }, { "type": "public-key", "alg": -257 } ],
    "timeout": 60000,
    "attestation": "none",
    "excludeCredentials": [ { "type": "public-key", "id": "…b64url…", "transports": ["internal"] } ],
    "authenticatorSelection": {
      "residentKey": "required",
      "requireResidentKey": true,
      "userVerification": "required"
    }
  }
}

• excludeCredentials obsahuje existujúce kľúče používateľa, takže ten istý autentifikátor sa nezaregistruje dvakrát.
• Jednorazová challenge sa uloží na serveri pod ceremonyId na challenge.ttl sekúnd.
• Bezstavová aplikácia pošle ceremonyId späť spolu s odpoveďou; aplikácia so session ho môže poslať späť alebo uložiť do session.

Odpoveď prehliadača

RegistrationResponseData::fromArray() načíta štandardný JSON z prehliadača a striktne dekóduje binárne položky z base64url: rawId (alebo id), ceremonyId, response.clientDataJSON, response.attestationObject a voliteľný zoznam response.transports. Poškodená odpoveď vyhodí InvalidClientData.

Čo overí register()

register() vykoná kontroly podľa WebAuthn §7.1 v predpísanom poradí a vráti uložený Passkey, alebo vyhodí podtriedu PasskeyException:

• clientDataJSON sa dá dekódovať a jeho typ je webauthn.create.
• Challenge pre ceremonyId existuje, bola vydaná pre registráciu a zhoduje sa (porovnanie v konštantnom čase).
• Challenge bola vydaná pre tohto používateľa — dodatočná ochrana pri registrácii administrátorom v mene používateľa.
• Origin je v allowliste a cross-origin politika je splnená.
• Atestačný objekt sa striktne dekóduje z CBOR, jeho fmt je platný identifikátor formátu a hash RP ID sa zhoduje.
• Príznak prítomnosti používateľa je nastavený, overenie používateľa tiež, ak sa vyžaduje, a príznaky zálohy sú konzistentné. Oprávnenosť na zálohu sa uloží do backup_eligible a počas života kľúča sa nemení.
• Sú prítomné atestované údaje kľúča s podporovaným a ponúknutým algoritmom.
• Atestačné vyhlásenie sa overí — alebo sa predvolene len zaznamená (pozri Atestácia).
• ID kľúča ešte nie je zaregistrované, vrátane odvolaných. Potom sa kľúč uloží a spustí sa PasskeyRegistered.

Nastavenia pre jedno volanie

Upravte jednu ceremóniu bez zmeny globálnych predvolieb — prázdne položky preberú hodnotu z konfigurácie. Okrem overenia používateľa, atestácie a časového limitu môžete vyžiadať aj cross-platform (roamingový bezpečnostný kľúč) alebo nerezidentný kľúč:

use RoundlyConsulting\Passkeys\DataTransferObjects\RegistrationOptionsOverrides;
use RoundlyConsulting\Passkeys\Enums\AttestationConveyance;
use RoundlyConsulting\Passkeys\Enums\AuthenticatorAttachment;
use RoundlyConsulting\Passkeys\Enums\ResidentKey;
use RoundlyConsulting\Passkeys\Enums\UserVerification;

$options = Passkeys::for($user)->registrationOptions(new RegistrationOptionsOverrides(
    userVerification: UserVerification::Preferred,
    attestation: AttestationConveyance::Direct,
    timeoutMs: 30_000,
    residentKey: ResidentKey::Discouraged,
    authenticatorAttachment: AuthenticatorAttachment::CrossPlatform,
));

Predvolené nastavenie zostáva residentKey: required (prihlásenie bez mena) a authenticatorSelection sa bez úprav serializuje bajt po bajte rovnako.

Priame použitie akcií

Obe volania sú samostatné akcie, ktoré si môžete vytiahnuť z kontajnera a zavolať sami (pozri DI a akcie):

use RoundlyConsulting\Passkeys\Actions\GenerateRegistrationOptionsAction;
use RoundlyConsulting\Passkeys\Actions\VerifyRegistrationAction;

$options = app(GenerateRegistrationOptionsAction::class)->execute($user, $overrides);
$passkey = app(VerifyRegistrationAction::class)->execute($user, $response, $name);

Balík neobsahuje routy, controllery, CSRF, validáciu, obmedzovanie pokusov ani JavaScript pre frontend. Pripravte jeden endpoint, ktorý vráti JSON s možnosťami, a druhý, ktorý prijme odpoveď prehliadača a zavolá Passkeys::for($user)->register().