Webauthn Laravel Package

Getting Started

Start by installing the package via Composer: composer require lbuchs/webauthn. Since it’s designed for framework integration (especially Laravel), begin by initializing the RelyingParty class with your app’s domain (rpId), name, and origin (e.g., https://yourapp.test). You’ll primarily interact with two core flows: registration and authentication.

1. On the client (frontend): Use navigator.credentials.create() for registration and navigator.credentials.get() for login—see the library’s examples for starter JS snippets.
2. In Laravel: Create AuthController endpoints: /webauthn/register/start, /webauthn/register/finish, and /webauthn/login/start, /webauthn/login/finish.
3. First use case: Enforce WebAuthn as MFA after password login. Trigger registration flow after successful password auth.

Look first at the examples/ directory in the repo (even if "unknown", examples are standard in WebAuthn libs) for Laravel-style workflows. The RelyingParty constructor is your entry point—review its config options: rpId, rpName, origin, and attestationTypes.

Implementation Patterns

• Challenge lifecycle: Generate a unique, cryptographically secure challenge per session/user. Store it (e.g., in session or cache) before sending to client. Use RelyingParty::startRegistration() / startAuthentication() for this.

• Credential storage: Save returned credentialId, publicKey, attestationType, transports, and signInCount in your users or dedicated webauthn_credentials table. The credentialId is base64-encoded binary—store as BINARY/VARBINARY or base64 string.

• Stateless RP ID handling: In Laravel, set rpId to your app’s host only (e.g., example.com, not sub.example.com) to support subdomain logins safely. Use config('app.url') to derive origin dynamically.

• User verification (UV) vs. user presence (UP): For passwordless login, enable userVerification = 'required'. For MFA, preferred or discouraged is fine. Configure via startAuthentication(['userVerification' => 'required']).

• Laravel-specific pattern: Wrap the library in a dedicated service (e.g., WebAuthnService) that handles DB persistence and integrates with your Authenticatable model. Example method: public function registerCredential($user, $response).

• Cross-platform vs. platform: Let users choose authenticator type by setting authenticatorSelection in config:

  $startResult = $rp->startRegistration($user, [
      'authenticatorSelection' => [
          'residentKey' => 'preferred',
          'userVerification' => 'preferred'
      ]
  ]);
  

Gotchas and Tips

• Challenge mismatch errors: If validationError: 'ChallengeMismatch' occurs, ensure challenges aren’t reused, regenerated, or stale. Always use fresh challenges per ceremony. Laravel session flash() can help avoid persistence mistakes.
• RP ID vs. domain mismatch: WebAuthn strictly enforces RP ID. If your app is at app.example.com, rpId must be example.com or app.example.com. Defaulting to the full URL (e.g., https://app.example.com) causes subtle failures.
• CORS and POST size limits: Client responses can be large (attestation objects). Increase post_max_size and upload_max_filesize in php.ini, and ensure your CORS config allows Content-Type: application/json.
• User handle serialization: The userHandle (unique per user) must be binary-safe. In Laravel, use Str::random(16) and store as binary field. Never use email or username directly.
• Attestation verification: By default, attestation is none for best compatibility. Only enable direct or indirect attestation if you need authenticator attestation (e.g., for compliance).
• Debugging tip: Log raw challenge + clientResponse.origin + clientResponse.challenge during development. Use webauthn/debug middleware or Laravel Telescope to inspect flow state.
• Extensibility: The library exposes low-level validators (e.g., AttestationValidator, AssertionValidator). Override them via dependency injection or extend RelyingParty to customize security policies (e.g., enforce AAGUID whitelist for corporate keys).
• Backup strategy: Allow multiple credentials per user. WebAuthn does not provide automatic backup/recovery—alert users during registration to use multiple devices.