sorah/webauthn-ruby

WebAuthn in ruby ― Ruby implementation of a WebAuthn Relying Party

WebAuthn 🔑

Easily implement WebAuthn in your ruby/rails app

What is WebAuthn?

• WebAuthn article with Google IO 2018 talk
• Web Authentication API draft article by Mozilla
• WebAuthn W3C Candidate Recommendation
• WebAuthn W3C Editor's Draft

Prerequisites

This gem will help your ruby server act as a conforming Relying-Party, in WebAuthn terminology. But for the Registration and Authentication ceremonies to work, you will also need

A conforming User Agent

Currently supporting Web Authentication API:

• Mozilla Firefox 60+
• Google Chrome 67+
• Google Chrome 65 & 66 (Disabled by default, go to chrome://flags to enable Web Authentication API feature)

A conforming Authenticator

• Security Key by Yubico (used to test/develop this gem)

NOTE: Firefox states (Firefox 60 release notes) they only support USB FIDO2 or FIDO U2F enabled devices in their current implementation (version 60). It's up to the gem's user to verify user agent compatibility if any other device wants to be used as the authenticator component.

Installation

Add this line to your application's Gemfile:

gem 'webauthn'

And then execute:

$ bundle

Or install it yourself as:

$ gem install webauthn

Usage

Registration

Initiation phase

credential_creation_options = WebAuthn.credential_creation_options

# Store the newly generated challenge somewhere so you can have it
# for the validation phase.
#
# You can read it from the resulting options:
credential_creation_options[:challenge]

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

Validation phase

attestation_object = "..." # As returned by `navigator.credentials.create`
client_data_json = "..." # As returned by `navigator.credentials.create`

attestation_response = WebAuthn::AuthenticatorAttestationResponse.new(
  attestation_object: attestation_object,
  client_data_json: client_data_json
)

# This value needs to match `window.location.origin` evaluated by
# the User Agent as part of the validation phase.
original_origin = "https://www.example.com"

if attestation_response.valid?(original_challenge, original_origin)
  # 1. Register the new user and
  # 2. Keep Credential ID and Credential Public Key under storage
  #    for future authentications
  #    Access by invoking:
  #      `attestation_response.credential.id`
  #      `attestation_response.credential.public_key`
else
  # Handle error
end

Authentication

Initiation phase

Assuming you have the previously stored Credential ID, now in variable credential_id

credential_request_options = WebAuthn.credential_request_options
credential_request_options[:allowCredentials] << { id: credential_id, type: "public-key" }

# Store the newly generated challenge somewhere so you can have it
# for the validation phase.
#
# You can read it from the resulting options:
credential_request_options[:challenge]

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

Validation phase

Assuming you have the previously stored Credential Public Key, now in variable credential_public_key

authenticator_data = "..." # As returned by `navigator.credentials.get`
client_data_json = "..." # As returned by `navigator.credentials.get`
signature = "..." # As returned by `navigator.credentials.get`

assertion_response = WebAuthn::AuthenticatorAssertionResponse.new(
  authenticator_data: authenticator_data,
  client_data_json: client_data_json,
  signature: signature
)

# This value needs to match `window.location.origin` evaluated by
# the User Agent as part of the validation phase.
original_origin = "https://www.example.com"

# This hash must have the id and its corresponding public key of the
# previously stored credential for the user that is attempting to sign in.
allowed_credential = {
  id: credential_id,
  publick_key: credential_public_key
}

if assertion_response.valid?(original_challenge, original_origin, allowed_credential: allowed_credential)
  # Sign in the user
else
  # Handle error
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests and code-style checks. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Commit message format

Each commit message follows the <type>: <message> format.

The "message" starts with lowercase and the "type" is one of:

• build: Changes that affect the build system or external dependencies
• ci: Changes to the CI configuration files and scripts
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• test: Adding missing tests or correcting existing tests

Inspired in a subset of Angular's Commit Message Guidelines.

Contributing

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

License

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