Devise::Webauthn

Devise::Webauthn is a Devise extension that adds WebAuthn support to your Rails application, allowing users to authenticate with passkeys and use security keys for two factor authentication.

Requirements

• Ruby: 2.7+
• JavaScript: This gem includes WebAuthn JavaScript as custom HTML elements. You'll need to import the JavaScript file in your application.

Installation

Add this line to your application's Gemfile:

gem 'devise-webauthn'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install devise-webauthn

Usage

First, ensure you have Devise set up in your Rails application. For a full guide on setting up Devise, refer to the Devise documentation. Then, follow these steps to integrate Devise::Webauthn:

1. Run Devise::Webauthn Generator: Run the generator to set up necessary configurations and migrations:

   $ bin/rails generate devise:webauthn:install

   You can optionally specify a different resource name (defaults to "user"):

   $ bin/rails generate devise:webauthn:install --resource-name=RESOURCE_NAME

   The generator will:

   • Create the WebAuthn initializer (config/initializers/webauthn.rb)
   • Generate the WebauthnCredential model and migration
   • Add webauthn_id field to your devise model (e.g., User)
   • Configure JavaScript loading for your application (see JavaScript Setup)

2. Run Migrations: After running the generator, execute the migrations to update your database schema:

   $ bin/rails db:migrate

3. Update Your Devise Model: Add :passkey_authenticatable to your Devise model (e.g., User) for passkeys authentication and :webauthn_two_factor_authenticatable for WebAuthn-based 2FA if desired. For example:

   class User < ApplicationRecord
     devise :database_authenticatable, :registerable,
            :recoverable, :rememberable, :validatable,
            :passkey_authenticatable, :webauthn_two_factor_authenticatable
   end

4. Configure WebAuthn Settings: Update the generated initializer file config/initializers/webauthn.rb with your application's specific settings, such as rp_name, and allowed_origins. For example:

    WebAuthn.configure do |config|
      # This value needs to match `window.location.origin` evaluated by
      # the User Agent during registration and authentication ceremonies.
      config.allowed_origins = ["https://yourapp.com"]
   
      # Relying Party name for display purposes
      config.rp_name = "Your App Name"
    end

Tip

You can find a working example on how to use this gem for passwordless and two factor authentication in devise-webauthn-rails-demo.

5. Include bundled WebAuthn JavaScript in your application: The install generator automatically configures JavaScript loading based on your setup:

   For importmap-rails:

   • Adds pin "devise/webauthn", to: "devise/webauthn.js" to config/importmap.rb
   • Adds import "devise/webauthn" to app/javascript/application.js

   For node setups (esbuild, Bun, etc.):

   • Adds <%= javascript_include_tag "devise/webauthn" %> to your application layout

   If the automatic setup doesn't work for your configuration, you can manually include the JavaScript:

   <%= javascript_include_tag "devise/webauthn" %>

Behavior

When the form is submitted:

1. The default form submission is prevented
2. The browser's WebAuthn prompt is triggered with the provided options
3. Upon successful authentication, the credential response is stored in the hidden input
4. The form is submitted with the credential data

How It Works

Passkey authentication

Adding Passkeys

Signed-in users can add passkeys by visiting /users/passkeys/new.

Sign In with Passkeys

When a user visits /users/sign_in they can choose to authenticate using a passkey. The authentication flow is handled by PasskeysAuthenticatable strategy.

The WebAuthn passkey sign-in flow works as follows:

1. User clicks "Sign in with Passkey", starting a WebAuthn authentication ceremony.
2. Browser shows available passkeys.
3. User selects a passkey and verifies with their authenticator.
4. The server verifies the response and signs in the user.

Two-Factor Authentication (2FA) with WebAuthn

Adding Security Keys for 2FA

Signed-in users can add security keys by visiting /users/second_factor_webauthn_credentials/new.

2FA Sign In with Security Keys

When a user that has 2FA enabled (i.e., has registered passkeys or security keys) visits /users/sign_in, after entering their primary credentials (e.g., email and password), they will be prompted to complete the second factor authentication using WebAuthn. The authentication flow is handled by WebauthnTwoFactorAuthenticatable strategy.

In a browser, the two factor authentication flow with WebAuthn works as follows:

1. User enters their primary credentials (e.g., email and password) and submits the form.
2. If the user has 2FA enabled, they are redirected to a second factor authentication page.
3. User clicks "Use security key", starting a WebAuthn authentication ceremony.
4. Browser shows available credentials (which can be both passkeys and security keys).
5. User selects a credential and verifies with their authenticator.
6. The server verifies the response and signs in the user.

Note

API clients are not redirected. Their password sign-in responds 401, and they complete the second factor with JSON requests. See Two-factor sign-in for API clients.

Challenge store

By default, WebAuthn challenges are kept in the session between the options request and the sign-in or registration request. To keep them in a cache instead:

# config/initializers/devise_webauthn.rb
Devise::Webauthn.challenge_store = :cache
# Optional. Defaults to Rails.cache and 5 minutes.
Devise::Webauthn::ChallengeStores::Cache.cache = Rails.cache
Devise::Webauthn::ChallengeStores::Cache.expires_in = 5.minutes

Each challenge can be used once. The two requests can reach different servers or processes, so use a cache shared by all your servers (Redis, Memcached or Solid Cache). ActiveSupport::Cache::MemoryStore and FileStore are local to one process or host.

API clients and native apps

Mobile apps and other API clients can use passkeys and security keys without a session cookie. They authenticate each request with a token instead, for example with devise-jwt.

Server setup

1. Keep challenges on the server. The default challenge store keeps each challenge in the session. A client without a session cookie loses it between the options request and the next request. Use the :cache challenge store with a cache shared by all your servers:

   # config/initializers/devise_webauthn.rb
   Devise::Webauthn.challenge_store = :cache

2. Stop Devise from writing the user to the session. Password, passkey and security key sign-in follow this setting:

   # config/initializers/devise.rb
   config.skip_session_storage = [:http_auth, :params_auth]

3. Respond with JSON. Add the format to the controller Devise inherits from (config.parent_controller, ApplicationController by default). Send Accept: application/json from the client.

   class ApplicationController < ActionController::Base
     respond_to :html, :json
   end

   • In an API-only app, inherit from ActionController::API, use respond_to :json, and set config.navigational_formats = [] in the Devise initializer. Otherwise a request without an Accept header counts as a browser request, and Devise raises when it writes to the session.
   • With :registerable, override sign_up in your registrations controller to call sign_in(resource_name, resource, store: false). Devise's default writes to the session.
4. Accept your native apps. Native apps do not have a browser origin. Tell WebAuthn which relying party and origins to accept:

   WebAuthn.configure do |config|
     config.rp_id = "example.com"
     config.allowed_origins = [
       "https://example.com",                            # web and iOS
       "android:apk-key-hash:<base64url SHA-256 of your signing certificate>"
     ]
   end

   Your domain must also serve /.well-known/apple-app-site-association (with webcredentials) and /.well-known/assetlinks.json (with delegate_permission/common.get_login_creds).
5. With devise-jwt, issue a token after two-factor sign-in. devise-jwt only issues a token on POST /users/sign_in by default. Add the two-factor path:

   config.jwt do |jwt|
     jwt.dispatch_requests = [["POST", %r{^/users/two_factor_authentication$}]]
   end

Endpoints

Send public_key_credential as the JSON object your WebAuthn library returns. For a resource named user:

Step	Request	Response
Sign-in options	POST /users/passkey_authentication_options	WebAuthn request options
Sign in	POST /users/sign_in with public_key_credential	201, and a JWT when you use devise-jwt
Registration options	POST /users/passkey_registration_options (authenticated)	WebAuthn creation options
Add passkey	POST /users/passkeys with name and public_key_credential (authenticated)	201, or 422 with errors
Delete passkey	DELETE /users/passkeys/:id (authenticated)	204
Security key registration options	POST /users/security_key_registration_options (authenticated)	WebAuthn creation options
Add security key	POST /users/second_factor_webauthn_credentials with name and public_key_credential (authenticated)	201, or 422 with errors
Promote security key to passkey	PATCH /users/second_factor_webauthn_credentials/:id (authenticated)	204
Delete security key	DELETE /users/second_factor_webauthn_credentials/:id (authenticated)	204

Two-factor sign-in for API clients

When a user has 2FA enabled, password sign-in takes three requests:

1. POST /users/sign_in with the email and password. The response is 401 with error and two_factor_token.
2. POST /users/security_key_authentication_options with two_factor_token. The response has the WebAuthn request options.
3. POST /users/two_factor_authentication with two_factor_token and public_key_credential. The response is 201, and a JWT when you use devise-jwt.

About the two_factor_token:

• Send it in the request body. The gem ignores it in the query string, and adds it to filter_parameters so Rails does not log it.
• It expires after 5 minutes (Devise::Webauthn::TwoFactorToken.expires_in).
• The response includes it only when skip_session_storage includes :params_auth. Otherwise the session keeps the pending sign-in, and the client sends no token.

Customization

Customizing Views

Similar to views customization on Devise, to customize the views, you can copy the view files from the gem into your application. Run the following command:

$ bin/rails generate devise:webauthn:views

If you want to customize only specific views, you can copy them individually. For example, to copy only the passkeys views:

$ bin/rails generate devise:webauthn:views -v passkeys

Helper methods

Devise::Webauthn provides helpers that can be used in your views. These helpers accept either a resource name (e.g., :user) or a resource object (e.g., @user) as the first argument.

For example, for a resource named user, you can use the following helpers:

To add a form for logging in with passkeys:

<%= login_with_passkey_form_for(:user) do |form| %>
  <%= form.submit "Log in with passkeys" %>
<% end %>

To add a form for logging in with security keys (2FA):

<%= login_with_security_key_form_for(@resource) do |form| %>
  <%= form.submit "Use security key" %>
<% end %>

To add a passkeys creation form:

<%= passkey_creation_form_for(:user) do |form| %>
  <%= form.label :name, 'Passkey name' %>
  <%= form.text_field :name, required: true %>
  <%= form.submit 'Create Passkey' %>
<% end %>

Handling unsupported WebAuthn

The custom elements check for WebAuthn API support when they connect to the DOM. If the browser doesn't support WebAuthn, a webauthn:unsupported event is dispatched and the form submission handler is not attached.

document.addEventListener('webauthn:unsupported', (event) => {
  const { action } = event.detail; // 'create' or 'get'

  // Hide the WebAuthn form and show a message
  hideWebauthnFormWithMessage('Your browser does not support WebAuthn');
});

Customizing Javascript Error Handling

By default, WebAuthn errors during registration or authentication are displayed using the browser's alert() dialog. You can customize this behavior by listening to the webauthn:prompt:error event.

Listening for WebAuthn Errors

The custom elements dispatch a webauthn:prompt:error event whenever an error occurs during the WebAuthn prompt interaction (registration or authentication). You can listen for this event and provide custom error handling:

document.addEventListener('webauthn:prompt:error', (event) => {
  event.preventDefault(); // Prevent the default alert

  const { error, action } = event.detail;

  // Your custom error handling
  console.error(`WebAuthn ${action} failed:`, error);
  showFlashMessage(error.message, 'error');
});

Event Details

The event includes the following information in event.detail:

• error: The error object thrown during the WebAuthn operation
• action: Either "create" (for registration) or "get" (for authentication)

Handling Specific Error Types

WebAuthn operations can fail for various reasons. Here are some common error types you might want to handle:

document.addEventListener('webauthn:prompt:error', (event) => {
  event.preventDefault();

  const { error, action } = event.detail;

  switch (error.name) {
    case 'NotAllowedError':
      // User cancelled the operation or timeout
      showFlashMessage('Operation cancelled or timed out', 'warning');
      break;

    default:
      // Generic error message
      showFlashMessage(`Authentication error: ${error.message}`, 'error');
  }
});

Different Handling for Registration vs Authentication

You can provide different error handling based on whether the error occurred during registration or authentication:

document.addEventListener('webauthn:prompt:error', (event) => {
  event.preventDefault();

  const { error, action } = event.detail;

  if (action === 'create') {
    // Handle registration errors
    handleRegistrationError(error);
  } else if (action === 'get') {
    // Handle authentication errors
    handleAuthenticationError(error);
  }
});

Note: If you don't call event.preventDefault(), the default alert() will still be shown.

Customizing Controllers

Similar to controllers customization on Devise, you can customize the Devise::Webauthn controllers.

1. Create your custom controllers using the generator which requires a scope:

$ bin/rails generate devise:webauthn:controllers [scope]

2. Tell the router to use your custom controllers. For example, if your scope is users:

devise_for :users, controllers: {
  passkeys: 'users/passkeys'
}

3. Change or extend the generated controllers as needed.

Customizing the WebAuthn user name

When a passkey or a security key is added, the registration options send webauthn_user_name as both the WebAuthn user.name and user.displayName. A passkey keeps this name, and the browser or operating system shows it when the user picks a passkey to sign in.

By default it is the first authentication key with a non-nil value, such as the email. If that key is nil on a saved record, such as a plain attr_accessor :login, override webauthn_user_name in your model:

class User < ApplicationRecord
  devise :database_authenticatable, :passkey_authenticatable, authentication_keys: [:login]

  attr_accessor :login

  def webauthn_user_name
    username.presence || email
  end
end

The method must return a non-blank string. If it returns nil, the registration options have no name or displayName, PublicKeyCredential.parseCreationOptionsFromJSON throws a TypeError in the browser, and the user cannot add the passkey or security key.

Manually implementing WebAuthn forms

The gem provides two custom HTML elements for WebAuthn operations. While the form helpers handle this automatically, you can use these elements directly for custom implementations.

<webauthn-create>

Used for registering new credentials (passkeys or security keys).

<form action="/passkeys" method="post">
  <webauthn-create data-options-url="<%= passkey_registration_options_path(:user) %>">
    <input type="hidden" name="public_key_credential" data-webauthn-target="response">
    <input type="text" name="name" placeholder="Passkey name">
    <button type="submit">Create Passkey</button>
  </webauthn-create>
</form>

Requirements:

• Must be wrapped in a <form> element
  • The form's action should point to the appropriate endpoint – you can use the provided url helpers:
    • For creating passkeys: passkeys_path(resource_name)
    • For creating 2FA security keys: second_factor_webauthn_credentials_path(resource_name)
• Requires a data-options-url attribute pointing to the endpoint serving the WebAuthn creation options – you can use the provided url helpers:
  • For passkey creation options: passkey_registration_options_path(resource_name)
  • For 2FA security key creation options: security_key_registration_options_path(resource_name)
• Must contain a hidden input with data-webauthn-target="response" to store the credential response
• Must contain the submit button – the element intercepts form submission, fetches the options, calls the WebAuthn API, stores the credential in the hidden input, and then re-submits the form

<webauthn-get>

Used for authenticating with existing credentials.

<form action="/users/sign_in" method="post">
  <webauthn-get data-options-url="<%= passkey_authentication_options_path(:user) %>">
    <input type="hidden" name="public_key_credential" data-webauthn-target="response">
    <button type="submit">Sign in with Passkey</button>
  </webauthn-get>
</form>

Requirements:

• Must be wrapped in a <form> element
  • The form's action should point to the appropriate endpoint – you can use the provided url helpers:
    • For passkey sign-in: session_path(resource_name)
    • For 2FA with WebAuthn: two_factor_authentication_path(resource_name)
• Requires a data-options-url attribute pointing to the endpoint serving the WebAuthn request options – you can use the provided url helpers:
  • For passkey authentication options: passkey_authentication_options_path(resource_name)
  • For 2FA security key authentication options: security_key_authentication_options_path(resource_name)
• Must contain a hidden input with data-webauthn-target="response" to store the credential response
• Must contain the submit button – the element intercepts form submission, fetches the options, calls the WebAuthn API, stores the credential in the hidden input, and then re-submits the form

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rspec to run the tests. To run the linter, use bundle exec rubocop.

Before submitting a pull request, ensure that tests and linter pass.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/cedarcode/devise-webauthn.

License

The gem is available as open source under the terms of the MIT License.