[opensourcedex]

webauthn-ruby is a free, open source identity & access management (iam) project written in Ruby and released under MIT. It has 774 GitHub stars, 70 forks and 12 open issues, and was last pushed 19 days ago. On this registry it ranks #34 of 36 tracked projects in Identity & Access Management (IAM), with 5 head-to-head comparisons available.

What is webauthn-ruby?

webauthn-ruby is an MIT-licensed Ruby gem that turns a Ruby or Rails web server into a conformant WebAuthn Relying Party, handling the server-side registration and authentication of public-key credentials — passkeys — for teams that want passwordless or two-factor login without implementing the W3C specification themselves.

What it is

webauthn-ruby is a server-side library published on RubyGems that makes a Ruby or Rails application act as a functional WebAuthn Relying Party. It carries out the server-side operations needed to register or authenticate a user's public-key credential, also called a passkey, including the cryptographic checks those ceremonies require. The project lives in the Ruby and Rails ecosystem, is distributed under the MIT licence, and shows 774 stars, 70 forks and 12 open issues on GitHub, with its most recent push dated 3 September 2026.

The concrete problem it solves is the verification work that a Ruby application would otherwise have to write and maintain itself. A server that wants passkeys must inspect registration and authentication responses, validate them against the W3C WebAuthn Recommendation, and handle attestation and cryptographic verification correctly; the gem replaces that hand-rolled Relying Party layer with a maintained implementation. It deliberately covers only one of the three pieces a complete WebAuthn deployment needs: alongside the library, an application still requires a conforming user agent and a conforming authenticator, such as a browser paired with a platform or roaming security key, and it must store the resulting credentials itself.

Key capabilities

  • Performs the server-side WebAuthn registration ceremony and authentication ceremony, including the cryptographic checks the specification requires of a Relying Party.
  • Parses and validates attestation statement formats, documented in the README under "Attestation Statement Formats".
  • Exposes a documented public API, described in the README's "API" section, for wiring the ceremonies into an existing user model.
  • Installs as the webauthn gem: add gem 'webauthn' to a Gemfile and run bundle, or run gem install webauthn.
  • Targets passkey and two-factor flows, as reflected in its topics: passkey, passkeys, passwordless-login, 2fa, fido2 and web-authentication.
  • Works with known conformant user agent and authenticator pairs, including Chrome for Android 70+ with Android's fingerprint platform authenticator, Microsoft Edge with the Windows 10 platform authenticator, Firefox for Desktop with a Yubico security key over USB, and Safari on iOS 13.3+ with a YubiKey 5 NFC.
  • Documents a testing process for integrations and a security policy with a private vulnerability reporting address, [email protected].

Who uses it and how

  • Rails developers adding passwordless login; the README points to webauthn-rails-demo-app as a working example of passwordless login in a Rails application.
  • Applications adding a second factor to password authentication, matching the 2FA and two-factor-authentication topics.
  • Services whose users span mobile and desktop browsers, since the supported user agent and authenticator pairs cover Android, iOS, Windows and desktop Firefox.
  • Teams that keep authentication logic inside their own application, because the gem is a library installed into the app rather than a hosted identity service.
  • Rails apps whose front end already calls the browser's Web Authentication API, since the library supplies only the server half of the ceremony.

Getting started

Add gem 'webauthn' to the application's Gemfile and run bundle, or install it directly with gem install webauthn. The README links to webauthn-rails-demo-app for a working Rails passwordless login example.

How it compares

The facts provided name no competing libraries or paid products, so webauthn-ruby stands alone in this registry as the Ruby entry for WebAuthn Relying Party work. Because no replaced products are listed, no licence, self-hosting, data-ownership or cost-model comparison against commercial alternatives can be drawn from the available material.

When to use it — and when not to

A self-hoster takes on the parts the gem does not provide: a conforming user agent and authenticator pair, credential storage in the host application, and the client-side work that triggers each ceremony. Teams outside Ruby and Rails, or those expecting a complete hosted identity product with its own user interface, should not pick it. The available README also defers usage detail to the companion demo application rather than showing inline code, so a quick evaluation depends on reading that separate repository, and the project currently carries 12 open issues.

project readme (upstream, from github) — read inline

webauthn-ruby

banner

Gem Build Conventional Commits Join the chat at https://gitter.im/cedarcode/webauthn-ruby

WebAuthn ruby server library

Makes your Ruby/Rails web server become a functional WebAuthn Relying Party.

Takes care of the server-side operations needed to register or authenticate a user's public key credential (also called a "passkey"), including the necessary cryptographic checks.

Table of Contents

Security

Please report security vulnerabilities to [email protected].

More: SECURITY

Background

What is WebAuthn?

WebAuthn (Web Authentication) is a W3C standard for secure public-key authentication on the Web supported by all leading browsers and platforms. WebAuthn is the standard that underpins passkeys, the phishing-resistant replacement for passwords.

Good Intros
In Depth

Prerequisites

This ruby library will help your Ruby/Rails server act as a conforming Relying-Party, in WebAuthn terminology. But for the Registration and Authentication ceremonies to fully work, you will also need to add two more pieces to the puzzle, a conforming User Agent + Authenticator pair.

Known conformant pairs are, for example:

  • Google Chrome for Android 70+ and Android's Fingerprint-based platform authenticator
  • Microsoft Edge and Windows 10 platform authenticator
  • Mozilla Firefox for Desktop and Yubico's Security Key roaming authenticator via USB
  • Safari in iOS 13.3+ and YubiKey 5 NFC via NFC

For a complete list:

Install

Add this line to your application's Gemfile:

gem 'webauthn'

And then execute:

$ bundle

Or install it yourself as:

$ gem install webauthn

Usage

You can find a working example on how to use this gem in a passwordless login in a Rails app in webauthn-rails-demo-app. If you want to see an example on how to use this gem as a second factor authenticator in a Rails application instead, you can check it in webauthn-2fa-rails-demo.

If you are migrating an existing application from the legacy FIDO U2F JavaScript API to WebAuthn, also refer to docs/u2f_migration.md.

Configuration

If you have a multi-tenant application or just need to configure WebAuthn differently for separate parts of your application (e.g. if your users authenticate to different subdomains in the same application), we strongly recommend you look at this Advanced Configuration section instead of this.

For a Rails application this would go in config/initializers/webauthn.rb.

WebAuthn.configure do |config|
  # This value needs to match `window.location.origin` evaluated by
  # the User Agent during registration and authentication ceremonies.
  # Multiple origins can be used when needed. Using more than one will imply you MUST configure rp_id explicitely. If you need your credentials to be bound to a single origin but you have more than one tenant, please see [our Advanced Configuration section](https://github.com/cedarcode/webauthn-ruby/blob/master/docs/advanced_configuration.md) instead of adding multiple origins.
  config.allowed_origins = ["https://auth.example.com"]

  # When operating within iframes or embedded contexts, you may need to restrict
  # which top-level origins are permitted to host WebAuthn ceremonies.
  #
  # crossOrigin / topOrigin verification is DISABLED by default:
  #   config.verify_cross_origin = false
  #
  # When `verify_cross_origin` is false, any `crossOrigin` / `topOrigin` values reported by the browser
  #    are ignored. As a result, credentials created or used within a cross-origin iframe will be treated
  #    as valid.
  #
  # When `verify_cross_origin` is true, you can either:
  #
  # (A) Allow only specific top-level origins to embed your ceremony
  #     (each entry must match the browser-reported `topOrigin` during registration/authentication):
  #
  #     config.allowed_top_origins = ["https://app.example.com"]
  #
  # (B) Forbid ANY cross-origin iframe usage altogether
  #     (this rejects creation/authentication whenever `crossOrigin` is true):
  #
  #     config.allowed_top_origins = []
  #
  # Note: if `verify_cross_origin` is not enabled, any values set in `allowed_top_origins`
  # will be ignored.

  # Relying Party name for display purposes
  config.rp_name = "Example Inc."

  # Optionally configure a client timeout hint, in milliseconds.
  # This hint specifies how long the browser should wait for any
  # interaction with the user.
  # This hint may be overridden by the browser.
  # https://www.w3.org/TR/webauthn/#dom-publickeycredentialcreationoptions-timeout
  # config.credential_options_timeout = 120_000

  # You can optionally specify a different Relying Party ID
  # (https://www.w3.org/TR/webauthn/#relying-party-identifier)
  # if it differs from the default one.
  #
  # In this case the default would be "auth.example.com", but you can set it to
  # the suffix "example.com"
  #
  # config.rp_id = "example.com"

  # Configure preferred binary-to-text encoding scheme. This should match the encoding scheme
  # used in your client-side (user agent) code before sending the credential to the server.
  # Supported values: `:base64url` (default), `:base64` or `false` to disable all encoding.
  #
  # config.encoding = :base64url

  # Possible values: "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "RS256", "RS384", "RS512", "RS1"
  # Default: ["ES256", "PS256", "RS256"]
  #
  # config.algorithms << "ES384"
end

Credential Registration

The ceremony where a user, a Relying Party, and the user’s client (containing at least one authenticator) work in concert to create a public key credential and associate it with the user’s Relying Party account. Note that this includes employing a test of user presence or user verification. [source]

Initiation phase
# Generate and store the WebAuthn User Handle the first time the user registers a credential
if !user.webauthn_user_handle
  user.update!(webauthn_user_handle: WebAuthn.generate_user_handle)
end

options = WebAuthn::Credential.options_for_create(
  user: { id: user.webauthn_user_handle, name: user.name },
  exclude: user.webauthn_credentials.map { |c| c.webauthn_id },
  authenticator_selection: {
    resident_key: "discouraged",  # For a passwordless login or 2FA. Use "required" for a passkey-based (passwordless and usernameless) login.
    user_verification: "required" # For a passwordless or passkey-based (passwordless and usernameless) login. Use "discouraged" for 2FA.
  }
)

# Store the newly generated challenge somewhere so you can have it
# for the verification phase.
session[:creation_challenge] = options.challenge

# Send `options` back to the browser, so that they can be used
# to call `navigator.credentials.create({ "publicKey": options })`
#
# You can call `options.as_json` to get a ruby hash with a JSON representation if needed.

# If inside a Rails controller, `render json: options` will just work.
# I.e. it will encode and convert the options to JSON automatically.

# For your frontend code, you might find the [built-in browser methods](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential) useful.
# The built-in `PublicKeyCredential.parseCreationOptionsFromJSON(options)` allows you to decode the options,
# and the built-in `credential.toJSON()` to send the `PublicKeyCredential` object back to the server.
Verification phase
# Assuming you're using the built-in `credential.toJSON()` to send the `PublicKeyCredential` object back
# in params[:publicKeyCredential]:
webauthn_credential = WebAuthn::Credential.from_create(params[:publicKeyCredential])

begin
  # Enforce user verification (pairs with the "required" request above). Omit for 2FA.
  webauthn_credential.verify(session[:creation_challenge], user_verification: true)

  # Store Credential ID, Credential Public Key and Sign Count for future authentications
  user.webauthn_credentials.create!(
    webauthn_id: webauthn_credential.id,
    public_key: webauthn_credential.public_key,
    sign_count: webauthn_credential.sign_count
  )
rescue WebAuthn::Error => e
  # Handle error
end

Credential Authentication

The ceremony where a user, and the user’s client (containing at least one authenticator) work in concert to cryptographically prove to a Relying Party that the user controls the credential private key associated with a previously-registered public key credential (see Registration). Note that this includes a test of user presence or user verification. [source]

Initiation phase
options = WebAuthn::Credential.options_for_get(
  # Pass `allow` when the user is already known (passwordless/2FA/reauth).
  # For a passkey-based (usernameless and passwordless) login, omit it and resolve the user from `user_handle` after `from_get`.
  allow: user.webauthn_credentials.map { |c| c.webauthn_id },
  user_verification: "required" # For a passwordless or passkey-based (passwordless and usernameless) login. Use "discouraged" for 2FA.
)

# Store the newly generated challenge somewhere so you can have it
# for the verification phase.
session[:authentication_challenge] = options.challenge

# Send `options` back to the browser, so that they can be used
# to call `navigator.credentials.get({ "publicKey": options })`

# You can call `options.as_json` to get a ruby hash with a JSON representation if needed.

# If inside a Rails controller, `render json: options` will just work.
# I.e. it will encode and convert the options to JSON automatically.

# For your frontend code, you might find the [built-in browser methods](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential) useful.
# The built-in `PublicKeyCredential.parseRequestOptionsFromJSON(options)` allows you to decode the options,
# and the built-in `credential.toJSON()` to send the `PublicKeyCredential` object back to the server.
Verification phase

You need to look up the stored credential for a user by matching the id attribute from the PublicKeyCredential interface returned by the browser to the stored credential_id. The corresponding public_key and sign_count attributes must be passed as keyword arguments to the verify method call.

# Assuming you're using the built-in `credential.toJSON()` to send the `PublicKeyCredential` object back
# in params[:publicKeyCredential]:
webauthn_credential = WebAuthn::Credential.from_get(params[:publicKeyCredential])

stored_credential = user.webauthn_credentials.find_by(webauthn_id: webauthn_credential.id)

begin
  webauthn_credential.verify(
    session[:authentication_challenge],
    public_key: stored_credential.public_key,
    sign_count: stored_credential.sign_count,
    user_verification: true # For a passwordless or passkey-based (passwordless and usernameless) login. Omit for 2FA.
  )

  # Update the stored credential sign count with the value from `webauthn_credential.sign_count`
  stored_credential.update!(sign_count: webauthn_credential.sign_count)

  # Continue with successful sign in or 2FA verification...

rescue WebAuthn::SignCountVerificationError => e
  # Cryptographic verification of the authenticator data succeeded, but the signature counter was less then or equal
  # to the stored value. This can have several reasons and depending on your risk tolerance you can choose to fail or
  # pass authentication. For more information see https://www.w3.org/TR/webauthn/#sign-counter
rescue WebAuthn::Error => e
  # Handle error
end

Extensions

The mechanism for generating public key credentials, as well as requesting and generating Authentication assertions, as defined in Web Authentication API, can be extended to suit particular use cases. Each case is addressed by defining a registration extension and/or an authentication extension.

When creating a public key credential or requesting an authentication assertion, a WebAuthn Relying Party can request the use of a set of extensions. These extensions will be invoked during the requested ceremony if they are supported by the WebAuthn Client and/or the WebAuthn Authenticator. The Relying Party sends the client extension input for each extension in the get() call (for authentication extensions) or create() call (for registration extensions) to the WebAuthn client. [source]

Extensions can be requested in the initiation phase in both Credential Registration and Authentication ceremonies by adding the extension parameter when generating the options for create/get:

# Credential Registration
creation_options = WebAuthn::Credential.options_for_create(
  user: { id: user.webauthn_user_handle, name: user.name },
  exclude: user.webauthn_credentials.map { |c| c.webauthn_id },
  extensions: { appidExclude: domain.to_s },
  authenticator_selection: {
    resident_key: "discouraged",  # For a passwordless login or 2FA. Use "required" for a passkey-based (passwordless and usernameless) login.
    user_verification: "required" # For a passwordless or passkey-based (passwordless and usernameless) login. Use "discouraged" for 2FA.
  }
)

# OR

# Credential Authentication
options = WebAuthn::Credential.options_for_get(
  allow: user.webauthn_credentials.map { |c| c.webauthn_id },
  extensions: { appid: domain.to_s }
)

Consequently, after these options are sent to the WebAuthn client:

The WebAuthn client performs client extension processing for each extension that the client supports, and augments the client data as specified by each extension, by including the extension identifier and client extension output values.

For authenticator extensions, as part of the client extension processing, the client also creates the CBOR authenticator extension input value for each extension (often based on the corresponding client extension input value), and passes them to the authenticator in the create() call (for registration extensions) or the get() call (for authentication extensions).

The authenticator, in turn, performs additional processing for the extensions that it supports, and returns the CBOR authenticator extension output for each as specified by the extension. Part of the client extension processing for authenticator extensions is to use the authenticator extension output as an input to creating the client extension output. [source]

Finally, you can check the values returned for each extension by calling client_extension_outputs and authenticator_extension_outputs respectively. For example, following the initialization phase for the Credential Authentication ceremony specified in the above example:

webauthn_credential = WebAuthn::Credential.from_get(credential_get_result_hash)

webauthn_credential.client_extension_outputs #=> { "appid" => true }
webauthn_credential.authenticator_extension_outputs #=> nil

A list of all currently defined extensions:

API

WebAuthn.generate_user_handle

Generates a WebAuthn User Handle that follows the WebAuthn spec recommendations.

WebAuthn.generate_user_handle # "lWoMZTGf_ml2RoY5qPwbwrkxrvTqWjGOxEoYBgxft3zG-LlrICvE-y8bxFi06zMyIOyNsJoWx4Fa2TOqoRmnxA"

WebAuthn.generate_user_id is also available as an alias.

WebAuthn::Credential.options_for_create(options)

Helper method to build the necessary PublicKeyCredentialCreationOptions to be used in the client-side code to call navigator.credentials.create({ "publicKey": publicKeyCredentialCreationOptions }).

creation_options = WebAuthn::Credential.options_for_create(
  user: { id: user.webauthn_user_handle, name: user.name },
  exclude: user.webauthn_credentials.map { |c| c.webauthn_id }
)

# Store the newly generated challenge somewhere so you can have it
# for the verification phase.
session[:creation_challenge] = creation_options.challenge

# Send `creation_options` back to the browser, so that they can be used
# to call `navigator.credentials.create({ "publicKey": creationOptions })`
#
# You can call `creation_options.as_json` to get a ruby hash with a JSON representation if needed.

# If inside a Rails controller, `render json: creation_options` will just work.
# I.e. it will encode and convert the options to JSON automatically.
WebAuthn::Credential.options_for_get([options])

Helper method to build the necessary PublicKeyCredentialRequestOptions to be used in the client-side code to call navigator.credentials.get({ "publicKey": publicKeyCredentialRequestOptions }).

request_options = WebAuthn::Credential.options_for_get(allow: user.webauthn_credentials.map { |c| c.webauthn_id })

# Store the newly generated challenge somewhere so you can have it
# for the verification phase.
session[:authentication_challenge] = request_options.challenge

# Send `request_options` back to the browser, so that they can be used
# to call `navigator.credentials.get({ "publicKey": requestOptions })`

# You can call `request_options.as_json` to get a ruby hash with a JSON representation if needed.

# If inside a Rails controller, `render json: request_options` will just work.
# I.e. it will encode and convert the options to JSON automatically.
WebAuthn::Credential.from_create(credential_create_result)
credential_with_attestation = WebAuthn::Credential.from_create(params[:publicKeyCredential])
WebAuthn::Credential.from_get(credential_get_result)
credential_with_assertion = WebAuthn::Credential.from_get(params[:publicKeyCredential])
PublicKeyCredentialWithAttestation#verify(challenge)

Verifies the created WebAuthn credential is valid.

credential_with_attestation.verify(session[:creation_challenge])
PublicKeyCredentialWithAssertion#verify(challenge, public_key:, sign_count:)

Verifies the asserted WebAuthn credential is valid.

Mainly, that the client provided a valid cryptographic signature for the corresponding stored credential public key, among other extra validations.

credential_with_assertion.verify(
  session[:authentication_challenge],
  public_key: stored_credential.public_key,
  sign_count: stored_credential.sign_count
)
PublicKeyCredential#client_extension_outputs
credential = WebAuthn::Credential.from_create(params[:publicKeyCredential])

credential.client_extension_outputs
PublicKeyCredential#authenticator_extension_outputs
credential = WebAuthn::Credential.from_create(params[:publicKeyCredential])

credential.authenticator_extension_outputs

Attestation

Attestation Statement Formats

Attestation Statement Format Supported?
packed (self attestation) Yes
packed (x5c attestation) Yes
tpm (x5c attestation) Yes
android-key Yes
android-safetynet Yes
apple Yes
fido-u2f Yes
none Yes

Attestation Types

You can define what trust policy to enforce by setting acceptable_attestation_types config to a subset of ['None', 'Self', 'Basic', 'AttCA', 'Basic_or_AttCA'] and attestation_root_certificates_finders to an object that responds to #find and returns the corresponding root certificate for each registration. The #find method will be called passing keyword arguments attestation_format, aaguid and attestation_certificate_key_id.

Testing Your Integration

The Webauthn spec requires for data that is signed and authenticated. As a result, it can be difficult to create valid test authenticator data when testing your integration. webauthn-ruby exposes WebAuthn::FakeClient for you to use in your tests. Example usage can be found in webauthn-ruby/spec/webauthn/authenticator_assertion_response_spec.rb.

Contributing

See the contributing file!

Bug reports, feature suggestions, and pull requests are welcome on GitHub at https://github.com/cedarcode/webauthn-ruby.

License

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

Frequently asked questions

Is webauthn-ruby free to use?

webauthn-ruby is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does webauthn-ruby do?

WebAuthn ruby server library ― Make your Ruby/Rails web server become a conformant WebAuthn Relying Party

What is webauthn-ruby written in?

webauthn-ruby is primarily written in Ruby. Its source is publicly available at https://github.com/cedarcode/webauthn-ruby, and it has 774 GitHub stars.