@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

1. Options endpoint (GET/POST) - Returns PublicKeyCredentialRequestOptions
2. Verification endpoint (POST) - Verifies the authentication response

For Registration

1. Options endpoint (GET/POST) - Returns PublicKeyCredentialCreationOptions
2. 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