Add RegistrationHelpers.authenticator_selection_options

* Adding `authenticator_selection_options` allows implementors to
	customize their authentication selection needs to match the needs of
	their userbase.
* By default, `RegistrationHelpers` should explicitly require that the
	credentials must be discoverable:
	> Passkeys are primarily driven by the use of discoverable credentials
	> Discoverable credentials are a mechanism provided by the WebAuthn
	> specification that allows for seamless authentication without the
	> user having to provide either a username or password. In fact,
	> WebAuthn credentials are determined to be passkeys based on
	> their “discoverability”.
	> ...
	> It’s important in our context of passkeys to focus primarily on
	> discoverable credentials; a WebAuthn credential is not considered a
	> passkey unless it’s discoverable.
	> https://developers.yubico.com/Passkeys/Passkey_concepts/Discoverable_vs_non-discoverable_credentials.html

* This detail, and the desire to have the gem as secure by default,
	means that the `resident_key` should be `required`. Some problems with
	non-discoverable credentials are:
	* We would have make assumptions on what user identifier is used
		(eg: username, email, phone number, employee ID, etc.), which makes
		this gem less flexible & usable in a variety of contexts
	* It opens up the possibility for dictionary/phishing on those user
		identifiers. If there is an endpoint where someone can query to
		return a list of credentials for an identifier, they can determine
		if someone is using a service by the presence of credentials.

* However, there is this caveat in the Yubico documentation:
	> Supporting non-discoverable credential flows is important for two
	> distinct reasons:
	> - A user may be using a pre-FIDO2 authenticator that does not
	> 	support discoverable credentials
	> - A user may be using an authenticator that does not have available
	>		room for more discoverable credentials
	> This will be especially important for consumer use cases where you
	> may not have control over the types of authenticators that your user
	> base will attempt to leverage.
	> https://developers.yubico.com/Passkeys/Passkey_concepts/Discoverable_vs_non-discoverable_credentials.html
	* While this edge case is **not** something that `warden-webauthn`
		supports out of the box, allowing `authenticator_selection_options`
		to be easily customizable makes it easy for an implementor to handle
		the edge case if it's truly needed.

Author: tcannonfodder

lib/warden/webauthn/registration_helpers.rb

@@ -8,7 +8,7 @@ def generate_registration_options(relying_party:, user_details:, exclude: [], op
         relying_party.options_for_registration(**{
           user: user_details,
           exclude: exclude,
-          authenticator_selection: { user_verification: "required" }
+          authenticator_selection: authenticator_selection_options
         }.merge(options))
       end
 
@@ -47,6 +47,10 @@ def raw_credential_key
       def registration_challenge_key
         "current_webauthn_registration_challenge"
       end
+
+      def authenticator_selection_options
+        { resident_key: "required", user_verification: "required" }
+      end
     end
   end
 end

test/warden/test_registration_helpers.rb

@@ -49,7 +49,7 @@ def test_generate_registration_options
     assert_equal 120_000, options_for_registration.timeout
     assert_equal relying_party, options_for_registration.relying_party
 
-    assert_equal ({user_verification: "required"}), options_for_registration.authenticator_selection
+    assert_equal ({ resident_key: "required", user_verification: "required" }), options_for_registration.authenticator_selection
 
     assert_kind_of WebAuthn::PublicKeyCredential::UserEntity, options_for_registration.user
 
@@ -83,7 +83,7 @@ def test_generate_registration_options_with_overrides
     assert_equal extensions, options_for_registration.extensions
     assert_equal expected_exclude_credentials, options_for_registration.exclude_credentials
 
-    assert_equal ({user_verification: "required"}), options_for_registration.authenticator_selection
+    assert_equal ({ resident_key: "required", user_verification: "required" }), options_for_registration.authenticator_selection
 
     assert_kind_of WebAuthn::PublicKeyCredential::UserEntity, options_for_registration.user
 
@@ -110,7 +110,7 @@ def test_generate_registration_options_with_customized_relying_party_id
     assert_equal 120_000, options_for_registration.timeout
     assert_equal relying_party, options_for_registration.relying_party
 
-    assert_equal ({user_verification: "required"}), options_for_registration.authenticator_selection
+    assert_equal ({ resident_key: "required", user_verification: "required" }), options_for_registration.authenticator_selection
 
     assert_kind_of WebAuthn::PublicKeyCredential::UserEntity, options_for_registration.user
 
@@ -297,6 +297,10 @@ def test_registration_challenge
 
     assert_equal challenge, @test_class.registration_challenge
   end
+
+  def test_authenticator_selection_options
+    assert_equal ({ resident_key: "required", user_verification: "required" }), @test_class.authenticator_selection_options
+  end
 end
 
 class Warden::TestRegistrationHelpersCustomChallengeKey < Minitest::Test
@@ -353,7 +357,7 @@ def test_generate_registration_options
     assert_equal 120_000, options_for_registration.timeout
     assert_equal relying_party, options_for_registration.relying_party
 
-    assert_equal ({user_verification: "required"}), options_for_registration.authenticator_selection
+    assert_equal ({ resident_key: "required", user_verification: "required" }), options_for_registration.authenticator_selection
 
     assert_kind_of WebAuthn::PublicKeyCredential::UserEntity, options_for_registration.user
 
@@ -387,7 +391,7 @@ def test_generate_registration_options_with_overrides
     assert_equal extensions, options_for_registration.extensions
     assert_equal expected_exclude_credentials, options_for_registration.exclude_credentials
 
-    assert_equal ({user_verification: "required"}), options_for_registration.authenticator_selection
+    assert_equal ({ resident_key: "required", user_verification: "required" }), options_for_registration.authenticator_selection
 
     assert_kind_of WebAuthn::PublicKeyCredential::UserEntity, options_for_registration.user
 
@@ -414,7 +418,7 @@ def test_generate_registration_options_with_customized_relying_party_id
     assert_equal 120_000, options_for_registration.timeout
     assert_equal relying_party, options_for_registration.relying_party
 
-    assert_equal ({user_verification: "required"}), options_for_registration.authenticator_selection
+    assert_equal ({ resident_key: "required", user_verification: "required" }), options_for_registration.authenticator_selection
 
     assert_kind_of WebAuthn::PublicKeyCredential::UserEntity, options_for_registration.user
 
@@ -600,4 +604,55 @@ def test_registration_challenge
 
     assert_equal challenge, @test_class.registration_challenge
   end
-end
+end
+
+class Warden::TestRegistrationHelpersCustomAuthenticatorSelection < Minitest::Test
+  include WebAuthnTestHelpers
+
+  class TestClass
+    include Warden::WebAuthn::RegistrationHelpers
+
+    attr_accessor :session, :params
+
+    def initialize
+      self.session = {}
+      self.params = {}
+    end
+
+    def authenticator_selection_options
+      { resident_key: "preferred", user_verification: "preferred" }
+    end
+  end
+
+  def setup
+    @test_class = TestClass.new
+  end
+
+  def test_authenticator_selection_options
+    assert_equal ({ resident_key: "preferred", user_verification: "preferred" }), @test_class.authenticator_selection_options
+  end
+
+  def test_generate_registration_options
+    relying_party = example_relying_party
+    user_details = {name: "Test User", id: WebAuthn.generate_user_id}
+    options_for_registration = @test_class.generate_registration_options(relying_party: relying_party, user_details: user_details)
+
+    assert_kind_of WebAuthn::PublicKeyCredential::CreationOptions, options_for_registration
+    assert_empty options_for_registration.exclude
+    assert_empty options_for_registration.exclude_credentials
+    assert_equal ({}), options_for_registration.extensions
+    assert_nil options_for_registration.rp.id
+
+    assert_equal 120_000, options_for_registration.timeout
+    assert_equal relying_party, options_for_registration.relying_party
+
+    assert_equal ({ resident_key: "preferred", user_verification: "preferred" }), options_for_registration.authenticator_selection
+
+    assert_kind_of WebAuthn::PublicKeyCredential::UserEntity, options_for_registration.user
+
+    assert_equal "Test User", options_for_registration.user.name
+    assert_equal "Test User", options_for_registration.user.display_name
+    refute_nil options_for_registration.user.id
+    refute_nil options_for_registration.challenge
+  end
+end