WebAuthn ruby server library ― Make your Ruby/Rails web server become a conformant WebAuthn Relying Party
Note: You are viewing the README for the development version of webauthn-ruby. For the current release version see https://github.com/cedarcode/webauthn-ruby/blob/2-stable/README.md.
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 credential, including the necessary cryptographic checks.
Please report security vulnerabilities to [email protected]
More: SECURITY
WebAuthn (Web Authentication) is a W3C standard for secure public-key authentication on the Web supported by all leading browsers and platforms.
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:
For a complete list:
Add this line to your application's Gemfile:
gem 'webauthn'
And then execute:
$ bundle
Or install it yourself as:
$ gem install webauthn
You can find a working example on how to use this gem in a Rails app in webauthn-rails-demo-app.
If you are migrating an existing application from the legacy FIDO U2F JavaScript API to WebAuthn, also refer to
docs/u2f_migration.md.
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. config.origin = "https://auth.example.com"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
orfalse
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
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]
# Generate and store the WebAuthn User ID the first time the user registers a credential if !user.webauthn_id user.update!(webauthn_id: WebAuthn.generate_user_id) endoptions = WebAuthn::Credential.options_for_create( user: { id: user.webauthn_id, name: user.name }, exclude: user.credentials.map { |c| c.webauthn_id } )
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 usedto 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 @github/webauthn-json npm package useful.
Especially for handling the necessary decoding of the options, and sending the
PublicKeyCredential
object back to the server.
# Assuming you're using @github/webauthn-json package to send the `PublicKeyCredential` object back # in params[:publicKeyCredential]: webauthn_credential = WebAuthn::Credential.from_create(params[:publicKeyCredential])begin webauthn_credential.verify(session[:creation_challenge])
Store Credential ID, Credential Public Key and Sign Count for future authentications
user.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
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]
options = WebAuthn::Credential.options_for_get(allow: user.credentials.map { |c| c.webauthn_id })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 usedto 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 @github/webauthn-json npm package useful.
Especially for handling the necessary decoding of the options, and sending the
PublicKeyCredential
object back to the server.
You need to look up the stored credential for a user by matching the
idattribute from the PublicKeyCredential interface returned by the browser to the stored
credential_id. The corresponding
public_keyand
sign_countattributes must be passed as keyword arguments to the
verifymethod call.
# Assuming you're using @github/webauthn-json package to send the `PublicKeyCredential` object back # in params[:publicKeyCredential]: webauthn_credential = WebAuthn::Credential.from_get(params[:publicKeyCredential])stored_credential = user.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 )
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
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_id, name: user.name }, exclude: user.credentials.map { |c| c.webauthn_id }, extensions: { appidExclude: domain.to_s } )OR
Credential Authentication
options = WebAuthn::Credential.options_for_get( allow: user.credentials.map { |c| c.webauthn_id }, extensions: { appid: domain.to_s } )
Consequently, after these
optionsare 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_outputsand
authenticator_extension_outputsrespectively. 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:
WebAuthn.generate_user_id
Generates a WebAuthn User Handle that follows the WebAuthn spec recommendations.
WebAuthn.generate_user_id # "lWoMZTGf_ml2RoY5qPwbwrkxrvTqWjGOxEoYBgxft3zG-LlrICvE-y8bxFi06zMyIOyNsJoWx4Fa2TOqoRmnxA"
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_id, name: user.name } exclude: user.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 usedto 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.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 usedto 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 Statement Format | Supported? | | -------- | :--------: | | packed (self attestation) | Yes | | packed (x5c attestation) | Yes | | tpm (x5c attestation) | Yes | | android-key | Yes | | android-safetynet | Yes | | fido-u2f | Yes | | none | Yes |
You can define what trust policy to enforce by setting
acceptable_attestation_typesconfig to a subset of
['None', 'Self', 'Basic', 'AttCA', 'Basic_or_AttCA']and
attestation_root_certificates_findersto an object that responds to
#findand returns the corresponding root certificate for each registration. The
#findmethod will be called passing keyword arguments
attestation_format,
aaguidand
attestation_certificate_key_id.
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/authenticatorassertionresponse_spec.rb.
Bug reports, feature suggestions, and pull requests are welcome on GitHub at https://github.com/cedarcode/webauthn-ruby.
The library is available as open source under the terms of the MIT License.