omniauth/webauthn

Installation

composer require omnisense/omniauth omniauth/webauthn

It requires omnisense/omniauth and web-auth/webauthn-lib (framework-free: its CBOR, COSE and PKI libraries, and the standalone Symfony components it is written on - serializer, property-info, uid, clock). No bundle, no framework: the passkeys stay in your table, behind Omniauth\WebAuthn\Contract\Passkeys, as PasskeyRecord values - the 13 fields of WebAuthn's credential record, as omnibase's userPasskey table holds them.

The whole thing by hand - the in-memory stores of Omniauth\Testing stand in for yours, and Omniauth\WebAuthn\Testing\SoftwareAuthenticator for the person's browser and device:

<?php

require 'vendor/autoload.php';

use Omniauth\ArrayState;
use Omniauth\Context;
use Omniauth\Factor;
use Omniauth\Method\Methods;
use Omniauth\Omniauth;
use Omniauth\WebAuthn\PasskeyMethod;
use Omniauth\WebAuthn\RelyingParty;
use Omniauth\WebAuthn\Testing\InMemoryPasskeys;
use Omniauth\WebAuthn\Testing\SoftwareAuthenticator;
use Omniauth\Testing\InMemoryStore;
use Omniauth\Testing\TestAccount;

$store = new InMemoryStore($ringo = new TestAccount('42', 'ringo', 'ringo@example.org', name: 'Ringo Starr'));
$passkeys = new InMemoryPasskeys($store);                  // yours: the userPasskey table

$session = [];                                             // $_SESSION, in a real page
$omniauth = new Omniauth(
    accounts: $store,
    methods: new Methods([
        new PasskeyMethod($store, $passkeys, new RelyingParty(id: 'example.org')),   // RELYING_PARTY_ID
    ]),
    state: new ArrayState($session),
);
$context = new Context(origin: 'https://example.org', host: 'example.org', ip: '203.0.113.7');
$browser = new SoftwareAuthenticator('https://example.org');

// From the account's settings: the creation options, then what the browser made of them.
$enrolment = $omniauth->enrol(Factor::Passkey, $ringo);
$options = $enrolment->begin($context);                    // JSON for PublicKeyCredential.parseCreationOptionsFromJSON()
$credential = $browser->create($options->payload);         // navigator.credentials.create(), then credential.toJSON()
echo $enrolment->confirm($context, ['json' => json_encode($credential), 'label' => 'MacBook'])->isDone() ? "registered\n" : "refused\n";
// registered

// Signing in: the request options, then the assertion. No account named: the person picks the passkey.
$options = $omniauth->begin('passkey', $context);          // JSON for PublicKeyCredential.parseRequestOptionsFromJSON()
$assertion = $browser->get($options->payload);             // navigator.credentials.get(), then credential.toJSON()
$result = $omniauth->verify('passkey', $context, ['json' => json_encode($assertion)]);
echo $result->status->value, ' as ', $result->account->identifier, ' by ', implode(' + ', array_map(fn ($f) => $f->value, $result->passed)), "\n";
// authenticated as ringo by passkey

What your page does around it is the host's part: it sends $options->payload as it is (the bridges add status: "ok" and errorMessage: "" around it, as web-auth/webauthn-symfony-bundle does, for assets/security/webauthn.js), posts the browser's JSON back, checks the CSRF token of the settings page, and on Authenticated renews its session id and keeps the account's handle.

No second factor follows a passkey (Marco's decision QA1): user verification is required at every ceremony - the device, and the gesture or the code that unlocks it.

Run in omniauth's harness on 2026-10-25 (the block as it is, Tests/DocsTest.php), it prints:

registered
authenticated as ringo by passkey

Next: the method, the records and the bundle.

The method

new PasskeyMethod(
    accounts: $accounts,                 // Omniauth\Contract\Accounts
    passkeys: $passkeys,                 // Omniauth\WebAuthn\Contract\Passkeys
    rp: new RelyingParty(
        id: 'example.org',               // RELYING_PARTY_ID; null: each request's host
        name: 'Les Ringo Stars',         // what some authenticators show; null: the id
        origins: [],                     // the origins allowed; []: the request's own
        insecure: ['localhost'],         // the ids allowed over plain http
    ),
    timeout: null,                       // milliseconds the browser gives the person; null: its own
);

A first factor. No second factor follows it (QA1): user verification is required at every ceremony.

Signing in

The proof is what the browser's credential.toJSON() gives, under json - or its keys as the proof itself. The passkey is found by its id (Passkeys::byCredentialId(base64)), its account by its user handle (Accounts::byHandle()); after the check, Passkeys::used() receives the record with its counter and backup flags moved.

Registering, from the settings

Refusals

The conductor throttles both steps (passkey, passkey.begin) like every method.

What the host does

Send Challenge::$payload as it is (the bridges wrap it as web-auth/webauthn-symfony-bundle did, status: "ok", errorMessage: "", so assets/security/webauthn.js stays as it is); post the browser's JSON back; check the settings page's CSRF token before a registration; on Authenticated, renew the session id.

The records and the bundle

A PasskeyRecord is a passkey as omnibase's userPasskey table holds it: the 13 fields of webauthn-lib's CredentialRecord, under the same names, in the values of the columns.

That text is what the bundle's DBAL types (base64, aaguid, trust_path, json) write, and what omnibase's own (passkey_base64, passkey_aaguid, passkey_trust_path, step AU1) reproduce:

$record = PasskeyRecord::fromRow($row);          // a row as the database gives it back (other columns ignored)
$row = $record->toRow();                         // the 13 columns as the bundle writes them
$credential = $record->toCredentialRecord();     // webauthn-lib's object, as omnibase's PasskeyRepository::credentialRecord() makes it
$record = PasskeyRecord::fromCredentialRecord($credential);   // as PasskeyRepository::fill() copies it

An application on Doctrine (omnibase) maps its entity's fields instead: the entity holds the bytes (its passkey_base64 type decodes them), so its store gives base64_encode() of them.

Both ways

So that the switch from the bundle (lesringostars at step AU7, then every site) loses no passkey, Tests/BundleCompatibilityTest checks:

1. registered by the bundle, signed in here: the row lesringostars' sign-in suite saw the bundle write when a passkey was added from the settings (AU1), recorded as it is; and live, the row the bundle's DBAL types write for the record webauthn-lib's attestation check makes - the same row;
2. registered here, read by the bundle: the row PasskeyMethod made, read through the bundle's DBAL types into the CredentialRecord its repository hands its authenticator, then a sign-in checked by webauthn-lib as the bundle configures it; what the bundle saves back equals what omniauth writes after the same sign-in.

One difference stays visible: the bundle asked userVerification: "preferred" (its default), this method asks "required" at both ceremonies. A passkey registered by the bundle without verification (uvInitialized false) signs in here only if the authenticator verifies the person this time.