@web-auth/webauthn-stimulus

@web-auth/webauthn-stimulus

WebAuthn Stimulus controllers for passwordless authentication in web applications.

This package provides ready-to-use Stimulus controllers for implementing WebAuthn/FIDO2 authentication (passkeys) in your web applications. It wraps @simplewebauthn/browser to provide an easy-to-use interface for credential registration and authentication.

Features

• 🔐 Passwordless authentication with WebAuthn/FIDO2
• 🔑 Passkey support (biometrics, security keys, platform authenticators)
• 🎯 Three specialized controllers: authentication, registration, and legacy combined
• 🌐 Browser autofill support (conditional UI)
• 📱 Platform authenticator detection (Face ID, Touch ID, Windows Hello)
• ⚡ Event-driven architecture for custom integrations
• 🎨 Framework agnostic (works with any Stimulus-enabled app)

Installation

npm install @web-auth/webauthn-stimulus

Dependencies

This package requires:

• @hotwired/stimulus ^3.0.0
• @simplewebauthn/browser ^13.2.0

These are listed as peer dependencies and should be installed in your project.

Usage with Module Bundlers

If you're using a module bundler (webpack, Vite, etc.) without Symfony UX, you can import controllers directly:

// Import individual controllers
import { AuthenticationController, RegistrationController } from '@web-auth/webauthn-stimulus';

// Or import specific ones
import AuthenticationController from '@web-auth/webauthn-stimulus/src/authentication-controller.js';

// Register with Stimulus
import { Application } from '@hotwired/stimulus';
const app = Application.start();
app.register('webauthn--authentication', AuthenticationController);

Available Controllers

1. Authentication Controller (authentication-controller.js)

Handles user sign-in with existing credentials.

<form data-controller="webauthn--authentication"
      data-webauthn--authentication-options-url-value="/auth/options"
      data-webauthn--authentication-result-url-value="/auth/verify"
      data-webauthn--authentication-conditional-ui-value="true"
      data-action="submit->webauthn--authentication#authenticate">
    <input type="text"
           name="username"
           autocomplete="username webauthn"
           data-webauthn--authentication-target="username">
    <input type="hidden" data-webauthn--authentication-target="result">
    <button type="submit">Sign In</button>
</form>

Features:

• Browser autofill support (conditional UI)
• Platform authenticator availability detection
• Flexible result handling (API or form submission)
• Optional redirect after success

2. Registration Controller (registration-controller.js)

Handles new credential registration (user sign-up).

<form data-controller="webauthn--registration"
      data-webauthn--registration-options-url-value="/register/options"
      data-webauthn--registration-result-url-value="/register/verify"
      data-action="submit->webauthn--registration#register">
    <input type="text"
           name="username"
           data-webauthn--registration-target="username">
    <input type="text"
           name="displayName"
           data-webauthn--registration-target="displayName">
    <select name="attestation" data-webauthn--registration-target="attestation">
        <option value="none">None</option>
        <option value="direct">Direct</option>
    </select>
    <input type="hidden" data-webauthn--registration-target="result">
    <button type="submit">Register</button>
</form>

Features:

• Configurable attestation level
• Resident key support
• User verification options
• Authenticator attachment preferences
• Auto-register mode (conditional create)

3. Legacy Controller (controller.js)

Combined controller for backward compatibility. Handles both registration and authentication.

<form data-controller="webauthn">
    <!-- Registration -->
    <button data-action="webauthn#signup">Sign Up</button>

    <!-- Authentication -->
    <button data-action="webauthn#signin">Sign In</button>
</form>

Configuration Values

Common Values (all controllers)

Value	Type	Description	Default
optionsUrl	String	URL to fetch options from	Required
resultUrl	String	URL to send result to	Required
submitViaForm	Boolean	Submit via form instead of API	false
successRedirectUri	String	Redirect URL after success	-

Authentication-specific Values

Value	Type	Description	Default
conditionalUi	Boolean	Enable browser autofill	false
verifyAutofillInput	Boolean	Verify autofill input exists	true

Registration-specific Values

Value	Type	Description	Default
autoRegister	Boolean	Enable auto-register mode	false

Events

All controllers dispatch custom events for integration:

Success Events

• webauthn:connect - Controller connected
• webauthn:options:request - Options requested
• webauthn:options:success - Options received
• webauthn:authenticator:response - Authenticator responded
• webauthn:attestation:success - Registration successful
• webauthn:assertion:success - Authentication successful

Error Events

• webauthn:unsupported - WebAuthn not supported
• webauthn:options:failure - Failed to get options
• webauthn:attestation:failure - Registration failed
• webauthn:assertion:failure - Authentication failed

Event Handling Example

document.addEventListener('webauthn:assertion:success', (event) => {
    console.log('Authentication successful!', event.detail);
});

document.addEventListener('webauthn:assertion:failure', (event) => {
    console.error('Authentication failed:', event.detail.exception);
});

Server-Side Integration

Your backend needs to provide two endpoints per operation:

For Authentication

• Options endpoint (GET/POST) - Returns PublicKeyCredentialRequestOptions
• Verification endpoint (POST) - Verifies the authentication response

For Registration

• Options endpoint (GET/POST) - Returns PublicKeyCredentialCreationOptions
• Verification endpoint (POST) - Verifies and stores the credential

See @simplewebauthn/server for server-side implementation examples.

Symfony Integration

This package is designed to work seamlessly with the web-auth/webauthn-framework Symfony bundle:

composer require web-auth/webauthn-stimulus

When installed via Composer with Symfony Flex, the controllers are automatically registered and available in your Twig templates:

<form {{ stimulus_controller('@web-auth/webauthn-stimulus/authentication') }}>
    {# ... #}
</form>

For detailed Symfony integration documentation, visit:

• Bundle documentation
• Main framework repository

Browser Support

Requires browsers with WebAuthn support:

• Chrome/Edge 67+
• Firefox 60+
• Safari 13+
• Opera 54+

Check support at runtime:

import { browserSupportsWebAuthn } from '@simplewebauthn/browser';

if (browserSupportsWebAuthn()) {
    // Show WebAuthn UI
}

Examples

With API Verification

<form data-controller="webauthn--authentication"
      data-webauthn--authentication-options-url-value="/api/auth/options"
      data-webauthn--authentication-result-url-value="/api/auth/verify"
      data-webauthn--authentication-success-redirect-uri-value="/dashboard">
    <!-- Form fields -->
</form>

With Form Submission

<form data-controller="webauthn--registration"
      data-webauthn--registration-options-url-value="/register/options"
      data-webauthn--registration-submit-via-form-value="true">
    <input type="hidden" data-webauthn--registration-target="result">
    <!-- Form fields -->
</form>

With Browser Autofill

<form data-controller="webauthn--authentication"
      data-webauthn--authentication-conditional-ui-value="true">
    <input type="text"
           name="username"
           autocomplete="username webauthn"
           data-webauthn--authentication-target="username">
</form>

Development

# Install dependencies
npm install

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Resources

• WebAuthn Guide - Introduction to WebAuthn
• SimpleWebAuthn Documentation - Library documentation
• Passkeys.dev - Passkey resources
• FIDO Alliance - WebAuthn standards

License

MIT - See LICENSE file for details.

Contributing

This is a sub-package of the web-auth/webauthn-framework monorepo.

Please submit issues and pull requests to the main repository:

• Issues: https://github.com/web-auth/webauthn-framework/issues
• Pull Requests: https://github.com/web-auth/webauthn-framework/pulls

Credits

• Author: Florent Morselli
• Contributors: All contributors