Download the PHP package jbtronics/2fa-webauthn without Composer

Webauthn Two-Factor-Authentication Plugin for scheb/2fa

This repository contains a plugin for scheb/2fa that adds support for Webauthn authenticators (like a Yubikey) as a second factor.

Features

• Support of all webauthn authenticators as second factor
• Supports multiple authenticators per user
• Backward compatibility for existing registered U2F keys (from r/u2f-two-factor-bundle)

Requirements

• Symfony 7
• PHP 8.2 or later
• webauthn/webauthn-lib 5.0 or later

If you want to use symfony 5. and PHP 7.4, use the version 1.0.0 of this bundle. If you want to use PHP 8.1 and webauthn/webauthn-lib 4., use the version 2.0.0 of this bundle.

Installation

1. Install the bundle composer require jbtronics/2fa-webauthn
2. Enable the bundle in your config/bundles.php (normally done by Symfony flex automatically)
3. If you want to use the easy doctrine integration, add the web-authn symfony bundle: composer require web-auth/webauthn-symfony-bundle. You do not need to run the community recipe, as we just use the doctrine type definitons from the bundle. Add Webauthn\Bundle\WebauthnBundle::class => ['all' => true], to your config/bundles.php instead.

Setup and Usage

After following the Installation steps, do the follwing steps to setup the library:

1. Add Jbtronics\TFAWebauthn\Model\TwoFactorInterface interface to your user entity:

2. Create a new entity for the webauthn keys. For simplicity we use the templates from the web-auth/webauthn-symfony-bundle (see here for more infos)

3. Include javascript frontend code into your project: For webauthn we need some javascript code to interact with the authenticators. Copy the file from assets/tfa_webauthn.js to your project and include it either by loading it via a <script> tag or by including it in your webpack using .addEntry().

4. Add configuration file config/packages/jbtronics_2fa_webauthn.yaml:

5. Customize the login template: Similar to the base login template of the scheb/2fa bundle you will most likely need to override the login template of this bundle to integrate it into your design. Copy the template from Resources/views/Authentication/form.html.twig to your project and customize it to your needs. Configure the template setting in the bundle config to your new path.

Registration of new keys

In principle the login with exsting keys should work now, but you will most likely need some possibility to register new keys. To make this easy there is the Jbtronics\TFAWebauthn\Services\TFAWebauthnRegistrationHelper service to help you with this:

1. Create a new controller, which will handle the registration, which should looks like this:

2. Create a template with a form, which will be used to register the new key. The form should look like this:

The data-webauthn-tfa-action attribute marks the form as webauthn registration form and is handled by the frontend code included above. If the form is submitted, the frontend code will catch that and start a registration process. The response is put it into the hidden input field with the id _auth_code and sent to our controller for parsing.

Migrate from r/u2f-two-factor-bundle

1. Replace the R\U2FTwoFactorBundle\Model\U2F\TwoFactorKeyInterface interface of your U2FKey entity with Jbtronics\TFAWebauthn\Model\LegacyU2FKeyInterface and remove the fromRegistrationData() function (as we do not need it anymore).
2. Replace the R\U2FTwoFactorBundle\Model\U2F\TwoFactorInterface interface of your user with Jbtronics\TFAWebauthn\Model\TwoFactorInterface, configure it (see above) and replace/rename your getU2FKeys() function to getLegacyU2FKeys().
3. (Optional:) If your appID is not the same as your domain, configure it with the U2FAppID option. But this should normally not be needed
4. Remove the old routes, templates and settings of the r/u2f-two-factor-bundle and remove it from your application
5. Follow the setup steps above

License

This bundle is licensed under the MIT license. See LICENSE for details.

Credits

• Webauthn support is provided by spomky-labs webauthn-framework
• This library is inspired by the r/u2f-two-factor-bundle bundle