PHPackages                             jbtronics/2fa-webauthn - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. jbtronics/2fa-webauthn

ActiveSymfony-bundle[Authentication & Authorization](/categories/authentication)

jbtronics/2fa-webauthn
======================

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

v3.0.0(9mo ago)1541.7k↑123.2%3[1 PRs](https://github.com/jbtronics/2fa-webauthn/pulls)MITPHPPHP ^8.2

Since Oct 3Pushed 9mo ago2 watchersCompare

[ Source](https://github.com/jbtronics/2fa-webauthn)[ Packagist](https://packagist.org/packages/jbtronics/2fa-webauthn)[ RSS](/packages/jbtronics-2fa-webauthn/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (9)Dependencies (9)Versions (10)Used By (0)

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

[](#webauthn-two-factor-authentication-plugin-for-scheb2fa)

This repository contains a plugin for [scheb/2fa](https://github.com/scheb/2fa) that adds support for Webauthn authenticators (like a Yubikey) as a second factor.

Features
--------

[](#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](https://github.com/darookee/u2f-two-factor-bundle))

Requirements
------------

[](#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
------------

[](#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
---------------

[](#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:

```
use Jbtronics\TFAWebauthn\Model\TwoFactorInterface as WebauthnTwoFactorInterface;

class User implements WebauthnTwoFactorInterface
{
    /**
     * @var Collection
     * @ORM\OneToMany(targetEntity="App\Entity\WebauthnKey", mappedBy="user", cascade={"REMOVE"}, orphanRemoval=true)
     */
    private $webauthnKeys;

    /**
     * Determines whether the user has 2FA using Webauthn enabled
     * @return bool True if the webauthn 2FA is enabled, false otherwise
     */
    public function isWebAuthnAuthenticatorEnabled(): bool
    {
        //Return true to enable webauthn 2FA
        return count($this->webauthnKeys) > 0;
    }

    /**
     * Returns a list of all legacy U2F keys, associated with this user
     * Return an empty array, if this user does not have any legacy U2F keys.
     * @return iterable
     */
    public function getLegacyU2FKeys(): iterable
    {
        return []; //If you have no legacy U2F keys, return just an empty array
        //return $this->u2f_keys; //Otherwise return the legacy keys (see migration section below)
    }

    /**
     * Returns a list of all webauthn keys, associated with this user
     * @return iterable
     */
    public function getWebauthnKeys(): iterable
    {
        return $this->webauthnKeys;
    }

    /**
     * Returns the webauthn user entity that should be used for this user.
     * @return PublicKeyCredentialUserEntity
     */
    public function getWebAuthnUser(): PublicKeyCredentialUserEntity
    {
        //Return webauthn user definition for this user. As we just use it as an two-factor authentication, the values here are most likely not that important
        return new PublicKeyCredentialUserEntity(
            $this->getUsername(), // The Webauthn Name (like a username)
            $this->getID(), // A unique identifier for this user
            $this->getDisplayName() // The display name of this user (optional, otherwise null)
        );
    }
}
```

2. Create a new entity for the webauthn keys. For simplicity we use the templates from the web-auth/webauthn-symfony-bundle (see [here](https://webauthn-doc.spomky-labs.com/v/v3.3/the-webauthn-server/the-symfony-way/entities-with-doctrine) for more infos)

```
declare(strict_types=1);

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;

use Webauthn\PublicKeyCredentialSource as BasePublicKeyCredentialSource;

#[ORM\Entity]
#[ORM\Table(name: 'webauthn_keys')]
class WebAuthnKey extends BasePublicKeyCredentialSource
{
    #[ORM\Id]
    #[ORM\Column(type: Types::INTEGER)]
    #[ORM\GeneratedValue]
    private $id;

    #[ORM\ManyToOne(targetEntity: User::class, inversedBy: 'webauthn_keys')]
    protected ?User $user = null;

    //You can declare additional fields too, if you want to store additional information about the key (like a name)
    private $name;

    public function getId(): string
    {
        return $this->id;
    }

    public static function fromRegistration(BasePublicKeyCredentialSource $registration): self
    {
        return new self(
            publicKeyCredentialId:  $registration->publicKeyCredentialId,
            type:  $registration->type,
            transports: $registration->transports,
            attestationType:  $registration->attestationType,
            trustPath:  $registration->trustPath,
            aaguid:  $registration->aaguid,
            credentialPublicKey:  $registration->credentialPublicKey,
            userHandle:  $registration->userHandle,
            counter:  $registration->counter,
            otherUI:  $registration->otherUI,
            backupEligible:  $registration->backupEligible,
            backupStatus:  $registration->backupStatus,
            uvInitialized:  $registration->uvInitialized,
        );
    }
}
```

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 `` tag or by including it in your webpack using `.addEntry()`.
4. Add configuration file `config/packages/jbtronics_2fa_webauthn.yaml`:

```
tfa_webauthn:
  enabled: true

  # Optional configuration options:

  # timeout: 60000 # The timeout in millisceconds to allow the user to interact with the authenticator. Default: 60000
  # template: '' # The template to use for the login form

  # rpID: null # The relying party ID of your application. If null, the current host will be used. Default: null
  # U2FAppID: null # The U2F AppID of your application. If null, the current host will be used. Default: null

  # These settings are most likely not important for two-factor authentication:
  # rpName: 'My Application' # The relying party name of your application, Default: 'My Application'
  # rpIcon: null # The relying party icon of your application. Default: null
```

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
------------------------

[](#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:

```
    use Jbtronics\TFAWebauthn\Services\TFAWebauthnRegistrationHelper;Ä

    class WebauthnKeyRegistrationController extends AbstractController
{
    /**
     * @Route("/webauthn/register", name="webauthn_register")
     */
    public function register(Request $request, TFAWebauthnRegistrationHelper $registrationHelper, EntityManagerInterface $em)
    {

        //If form was submitted, check the auth response
        if ($request->getMethod() === 'POST') {
            $webauthnResponse = $request->request->get('_auth_code');

            //Retrieve other data from the form, that you want to store with the key
            $keyName = $request->request->get('keyName');

            try {
                //Check the response
                $new_key = $registrationHelper->checkRegistrationResponse($webauthnResponse);
            } catch (Exception $exception) {
                // Handle errors...
            }

            //If we got here, the registration was successful. Now we can store the new key in the database

            //Convert our returned key into an database entity and persist it...
            $keyEntity = WebauthnKey::fromRegistration($new_key);
            $keyEntity->setName($keyName);
            $keyEntity->setUser($this->getUser());

            $em->persist($keyEntity);
            $em->flush();

            $this->addFlash('success', 'Key registered successfully');
            //We are finished here so return to another page
            return $this->redirectToRoute('homepage');
        }

        return $this->render(
            'webauthn_register.html.twig',
            [
                //Generate the registration request
                'registrationRequest' => $registrationHelper->generateRegistrationRequestAsJSON(),
            ]
        );
    }
}
```

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

```

    Add new Key

```

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
------------------------------------

[](#migrate-from-ru2f-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
-------

[](#license)

This bundle is licensed under the MIT license. See [LICENSE](LICENSE) for details.

Credits
-------

[](#credits)

- Webauthn support is provided by [spomky-labs webauthn-framework](https://github.com/web-auth/webauthn-framework)
- This library is inspired by the [r/u2f-two-factor-bundle](r/u2f-two-factor-bundle) bundle

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance58

Moderate activity, may be stable

Popularity39

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 98.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~130 days

Recently: every ~154 days

Total

9

Last Release

277d ago

Major Versions

v1.0.0 → v2.0.02023-06-11

v2.2.3 → v3.0.02025-08-14

PHP version history (3 changes)v1.0.0PHP ^7.4.0|^8.0

v2.0.0PHP ^8.1

v3.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/966f0c4a6fd593c7a9e3e0c950f4e44dfa6caaf09609500cdce765b1eba7a855?d=identicon)[jbtronics](/maintainers/jbtronics)

---

Top Contributors

[![jbtronics](https://avatars.githubusercontent.com/u/5410681?v=4)](https://github.com/jbtronics "jbtronics (57 commits)")[![ownede](https://avatars.githubusercontent.com/u/442603?v=4)](https://github.com/ownede "ownede (1 commits)")

---

Tags

2fasymfonysymfony-bundletwo-factortwo-factor-authenticationwebauthnsymfony2faTwo Factor AuthenticationwebauthnSymfony Bundlescheb-2fa

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jbtronics-2fa-webauthn/health.svg)

```
[![Health](https://phpackages.com/badges/jbtronics-2fa-webauthn/health.svg)](https://phpackages.com/packages/jbtronics-2fa-webauthn)
```

###  Alternatives

[web-auth/webauthn-framework

FIDO2/Webauthn library for PHP and Symfony Bundle.

50570.7k1](/packages/web-auth-webauthn-framework)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[web-auth/webauthn-symfony-bundle

FIDO2/Webauthn Security Bundle For Symfony

63397.4k6](/packages/web-auth-webauthn-symfony-bundle)[web-auth/webauthn-lib

FIDO2/Webauthn Support For PHP

1225.3M72](/packages/web-auth-webauthn-lib)[scheb/2fa-bundle

A generic interface to implement two-factor authentication in Symfony applications

7014.0M62](/packages/scheb-2fa-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)