First of all, thank you for contributing.

Bugs or feature requests can be posted online on the GitHub issues section of the project.

Few rules to ease code reviews and merges:

• You MUST run the test suite (see below).

• You MUST write (or update) unit tests when bugs are fixed or features are added.

• You SHOULD write documentation.

We use the following branching workflow:

• Each minor version has a dedicated branch (e.g. v1.1, v1.2, v2.0, v2.1…)

• The default branch is set to the last minor version (e.g. v2.1).

Your PR should NOT be submitted to the master branch but to the last minor version branch or to another minor version in case of bug fix.

Run test suite

• install composer: curl -s http://getcomposer.org/installer | php

• install dependencies: php composer.phar install

• run tests: vendor/bin/phpunit

Webauthn defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users.

This framework contains PHP libraries and Symfony bundle to allow developers to integrate that authentication mechanism into their web applications.

Class, Constant and Property Names

Naming things may be complicated. That’s why the following rule applies on the whole framework: the name of classes, constants and properties are identical to the ones you will find in the specification.

• authenticatorData

• signature

• userHandle

Supported features

• Attestation Types

  • Empty

  • Basic

  • Self

  • Private CA

  • Anonymization CA

  • Elliptic Curve Direct Anonymous Attestation (ECDAA)

• Attestation Formats

  • FIDO U2F

  • Packed

  • TPM

  • Android Key

  • Android Safetynet

  • Apple

• Token Binding support

• Cose Algorithms

  • RS1, RS256, RS384, RS512

  • PS256, PS384, PS512

  • ES256, ES256K, ES384, ES512

  • ED25519

• Extensions

  • Supported (not fully tested)

  • appid extension (compatibility with FIDO U2F authenticator)

Compatible Authenticators

The framework is already compatible with all authenticators except the ones that use ECDAA Attestation format.

The compliance of the framework is ensured by running unit and functional tests during its development.

Support

I bring solutions to your problems and answer your questions.

Contributing

Requests for new features, bug fixed and all other ideas to make this framework useful are welcome.

An Authenticator is a cryptographic entity used to generate a public key credential and registered by a Relying Party (i.e. an application). This public key is used to authenticate by potentially verifying a user in the form of an authentication assertion and other data.

Authenticators may have additional features such as PIN code or biometric sensors (fingerprint, facial recognition…) that offer user verification.

Roaming Authenticators

The roaming authenticator may have different forms. The most common form is a USB device the user plugs into its computer. It can be a paired Bluetooth device or a card with NFC capabilities.

Authenticators of this class are removable from, and can "roam" among, client devices.

Platform Authenticators

A platform authenticator is usually not removable from the client device. For example an Android smartphone or a Windows 10 computer with the associated security chips can act as an authenticator.

In the Webauthn context, there are two ceremonies:

• The attestation ceremony: it corresponds to the registration of a new authenticator,

• The assertion ceremony: it is used for the authentication of a user.

For both ceremonies, there are two steps to perform:

1. The creation of options: these options are sent to the authenticator and indicate what to do and how.

2. The response of the authenticator: after the user interacted with the authenticator, the authenticator computes a response that has to be verified.

Depending on the options and the capabilities of the authenticator, the user interaction may differ. It can be a simple touch on a button or a complete authentication using biometric means (PIN code, fingerprint, facial recognition…).

Attestation Statement

During the Attestation Ceremony (i.e. the registration of the authenticator), you can ask for the Attestation Statement of the authenticator. The Attestation Statements have one of the following types:

• None (none): no Attestation Statement is provided

• Basic Attestation (basic): Authenticator’s attestation key pair is specific to an authenticator model.

• Surrogate Basic Attestation (or Self Attestation - self): Authenticators that have no specific attestation key use the credential private key to create the attestation signature

• Attestation CA (AttCA): Authenticators are based on a Trusted Platform Module (TPM). They can generate multiple attestation identity key pairs (AIK) and requests an Attestation CA to issue an AIK certificate for each.

• Anonymization CA (AnonCA): Authenticators use an Anonymization CA, which dynamically generates per-credential attestation certificates such that the attestation statements presented to Relying Parties do not provide uniquely identifiable information.

• Elliptic Curve based Direct Anonymous Attestation (ECDAA): Authenticator receives direct anonymous attestation (DAA) credentials from a single DAA-Issuer. These DAA credentials are used along with blinding to sign the attested credential data.

Metadata Statement

The Metadata Statements are issued by the manufacturers of the authenticators. These statements contain details about the authenticators (supported algorithms, biometric capabilities...) and all the necessary information to verify the Attestation Statements generated during the attestation ceremony.

After the registration of an authenticator, you will get a Public Key Credential Source object. It contains all the credential data needed to perform user authentication and much more.

Each Credential Source is managed using the Public Key Credential Source Repository.

The library does not provide any concrete implementation. It is up to you to create it depending on your application constraints. This only constraint is that your repository class must implement the interface Webauthn\PublicKeyCredentialSourceRepository.

The PublicKeyCredentialSourceRepository interface requires the following methods to be implemented:

• public function findOneByCredentialId(string $publicKeyCredentialId): ?PublicKeyCredentialSource; : thie method retreive a key source object from the credential ID.

• public function findAllForUserEntity(PublicKeyCredentialUserEntity $publicKeyCredentialUserEntity): array;: this method lists all key sources associated to the user entity

• public function saveCredentialSource(PublicKeyCredentialSource $publicKeyCredentialSource): void;: this method saves the key source in your storage (files, database...)

This framework contains several sub-packages that you don’t necessarily need. It is highly recommended to install what you need and not the whole framework.

The preferred way to install the library you need is to use composer:

composer require web-auth/webauthn-lib

Hereafter the dependency tree:

• web-auth/webauthn-lib: this is the core library. This package can be used in any PHP project or within any popular framework (Laravel, CakePHP…)

• web-auth/webauthn-symfony-bundle: this is a Symfony bundle that ease the integration of this authentication mechanism in your Symfony project.

The core library also depends on web-auth/cose-lib and web-auth/metadata-service. What are these dependencies?

Framework and Dependency Sizes

The total size of the core package is approximately 760ko. Hereafter the detail for each component:

• web-auth/cose-lib: 85ko

• web-auth/metadata-service: 81ko

• web-auth/webauthn-lib: 207ko

• web-auth/webauthn-symfony-bundle: 385ko

The total size of the core package + the direct dependencies is approximately 1.7Mo.

Webauthn is now supported by all main web browsers:

• Mozilla Firefox 60+ and Firefox for Android 68+

• Google Chrome 67+

• Microsoft EDGE 18+ and Microsoft EDGE Chromium 79+

• Opera 54+

• Safari 13+ and iOS Safari 13.3+

• Android Browser 76+

You will interact with the authenticators through an HTML page and Javascript using the Webauthn API.

Installation

You can use npm or yarn to install the package:

npm i @web-auth/webauthn-helper
#or
yarn add @web-auth/webauthn-helper

Registration

// Import the registration hook
import {useRegistration} from 'webauthn-helper';

// Create your register function.
// By default the urls are "/register" and "/register/options"
// but you can change those urls if needed.
const register = useRegistration({
    actionUrl: '/api/register',
    optionsUrl: '/api/register/options'
});


// We can call this register function whenever we need (e.g. form submission)
register({
    username: 'john.doe',
    displayName: 'JD'
})
    .then((response) => console.log('Registration success'))
    .catch((error) => console.log('Registration failure'))
;

Additional options can be set during the registration process. See the section “Deep into the framework” to know more. Hereafter another example:

register({
    username: 'john.doe',
    displayName: 'JD',
    attestation: 'none',
    authenticatorSelection: {
        authenticatorAttachment: 'platform',
        requireResidentKey: true,
        userVerification: 'required'
    }
})
    .then((response) => console.log('Registration success'))
    .catch((error) => console.log('Registration failure'))
;

Authentication

// Import the login hook
import {useLogin} from 'webauthn-helper';

// Create your login function.
// By default the urls are "/login" and "/login/options"
// but you can change those urls if needed.
const login = useLogin({
    actionUrl: '/api/login',
    optionsUrl: '/api/login/options'
});


// We can call this login function whenever we need (e.g. form submission)
login({
    username: 'john.doe'
})
    .then((response) => console.log('Authentication success'))
    .catch((error) => console.log('Authentication failure'))
;

As done during the registration, additional options are available. See the section “Deep into the framework” to know more. Hereafter another example:

login({
    username: 'john.doe',
    userVerification: 'required'
})
    .then((response) => console.log('Authentication success'))
    .catch((error) => console.log('Authentication failure'))
;

When receiving a Webauthn Response, the property tokenBinding in the Webauthn\CollectedClientData object has one of the following values:

• null: the token binding is not supported by the browser

• "supported": the browser supports token binding, but no negotiation was performed during the communication

• "present": the browser supports token binding, and it is present in the response. The token binding ID is provided.

This feature is not yet implemented in the library, but you can decide how the library will react in case of the presence of the token binding ID.

The library provides two concrete classes for the moment:

• Webauthn\TokenBinding\IgnoreTokenBindingHandler: the library will ignore the token binding (recommended),

• Webauthn\TokenBinding\TokenBindingNotSupportedHandler: the library will throw an exception if the token binding is present.

You can change this behavior by creating your own implementation. The handler must implement the interface Webauthn\TokenBinding\TokenBindingHandler.

To launch a Webauthn server, you will need the following components:

That’s a lot off classes! But don’t worry, as their configuration is the same for all your application, you just have to set them once. Let’s see all of these in the next sections.

Public Key Credential Source Repository

The Public Key Credential Source Repository must implement Webauthn\PublicKeyCredentialSourceRepository. It will retrieve the credential source and update them when needed.

You can implement the required methods the way you want: Doctrine ORM, file storage…

Token Binding Handler

The token binding handler is a service that will verify if the token binding set in the device response corresponds to the one set in the request.

Attestation Statement Support Manager

Every Creation Responses contain an Attestation Statement. This attestation contains data regarding the authenticator depending on several factors such as its manufacturer and model, what you asked in the options, the capabilities of the browser or what the user allowed.

Supported Attestation Statement Types

• none: no attestation is provided.

• fido-u2f: for non-FIDO2 compatible devices (old U2F security tokens).

• packed: generally used by authenticators with limited resources (e.g., secure elements). It uses a very compact but still extensible encoding method.

• android key: commonly used by old or disconnected Android devices.

• android safety net: for new Android devices like smartphones.

• trusted platform module: for devices with built-in security chips.

• apple: for Apple devices

Attestation Object Loader

This object will load the Attestation statements received from the devices. It will need the Attestation Statement Support Manager created above.

Public Key Credential Loader

This object will load the Public Key using from the Attestation Object.

Extension Output Checker Handler

If you use extensions, you may need to check the value returned by the security devices. This behaviour is handled by an Extension Output Checker Manager.

You can add as many extension checkers as you want. Each extension checker must implement Webauthn\AuthenticationExtensions\ExtensionOutputChecker and throw a Webauthn\AuthenticationExtensions\ExtensionOutputError in case of an error.

Algorithm Manager

The Webauthn data verification is based on cryptographic signatures and thus you need to provide cryptographic algorithms to perform those checks.

We recommend the use of the following algorithms to cover all types of Authenticators. Feel free to adapt this list depending on your needs.

Authenticator Attestation Response Validator

This object is what you will directly use when receiving Attestation Responses (authenticator registration).

Authenticator Assertion Response Validator

This object is what you will directly use when receiving Assertion Responses (user authentication).

User verification may be instigated through various authorization gesture modalities: a touch plus PIN code, password entry, or biometric recognition (presenting a fingerprint). The intent is to be able to distinguish individual users.

Eligible authenticators are filtered and only capable of satisfying this requirement will interact with the user.

Possible user verification values are:

• required: this value indicates that the application requires user verification for the operation and will fail the operation if the response does not have the UV flag set.

• preferred: this value indicates that the application prefers user verification for the operation if possible, but will not fail the operation if the response does not have the UV flag set.

• discouraged: this value indicates that the application does not want user verification employed during the operation (e.g.,in the interest of minimizing disruption to the user interaction flow).

Public constants are provided by AuthenticatorSelectionCriteria.

• AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED

• AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED

• AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_DISCOURAGED

The mechanism for generating public key credentials, as well as requesting and generating Authentication assertions, can be extended to suit particular use cases. Each case is addressed by defining a registration extension.

Among the available extensions, you have:

• loc: The location registration extension and authentication extension provides the client device's current location to the WebAuthn Relying Party, if supported by the client platform and subject to user consent.

• hmac-secret: This registration extension and authentication extension enables the platform to retrieve a symmetric secret scoped to the credential from the authenticator.

• minPinLength: This registration extension returns the current minimum PIN length value to the Relying Party.

The Relying Party (or rp) corresponds to the application that will ask for the user to interact with the authenticator.

The library provides a simple class to handle the rp information: Webauthn\PublicKeyCredentialRpEntity.

<?php

use Webauthn\PublicKeyCredentialRpEntity;

$rpEntity = PublicKeyCredentialRpEntity::create(
    'ACME Webauthn Server' // The application name
);

This $rpEntity object will be useful for the next steps.

Relying Party ID

In the example above, we created a simple relying party object with it’s name. The relying party may also have an ID that corresponds to the domain applicable for that rp. By default, the relying party ID is null i.e. the current domain will be used.

It may be useful to specify the rp ID, especially if your application has several sub-domains. The rp ID can be set during the creation of the object as 2nd constructor parameter.

<?php

use Webauthn\PublicKeyCredentialRpEntity;

$rpEntity = PublicKeyCredentialRpEntity::create(
    'ACME Webauthn Server', // The application name
    'acme.com'              // The application ID = the domain
);

The rp ID shall be the domain of the application without the scheme, userinfo, port, path, user…. IP addresses are not allowed either.

How to determine the Relying Party ID?

The Relying Party ID should be determined depending on the common URLs for your web application.

If the domain is shared between sub-projects, the rp ID should be limited to that sub-projects.

For example, a web site is located at https://(www.)site1.host.com and another at https://(www.)site2.host.com, then the Relying Party IDs should be site1.host.com and site2.host.com respectively. If you set host.com, there is a risk that users from site1.host.com can log in at site2.host.com.

Relying Party Icon

Your application may also have a logo. You can indicate this logo as third argument. Please note that for safety reason this icon is a priori authenticated URL i.e. an image that uses the data scheme.

<?php

use Webauthn\PublicKeyCredentialRpEntity;

$rpEntity = PublicKeyCredentialRpEntity::create(
    'ACME Webauthn Server',
    'acme.com',
    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAUCAMAAAC6V+0/AAAAwFBMVEXm7NK41k3w8fDv7+q01Tyy0zqv0DeqyjOszDWnxjClxC6iwCu11z6y1DvA2WbY4rCAmSXO3JZDTxOiwC3q7tyryzTs7uSqyi6tzTCmxSukwi9aaxkWGga+3FLv8Ozh6MTT36MrMwywyVBziSC01TbT5ZW9z3Xi6Mq2y2Xu8Oioxy7f572qxzvI33Tb6KvR35ilwTmvykiwzzvV36/G2IPw8O++02+btyepyDKvzzifvSmw0TmtzTbw8PAAAADx8fEC59dUAAAA50lEQVQYV13RaXPCIBAG4FiVqlhyX5o23vfVqUq6mvD//1XZJY5T9xPzzLuwgKXKslQvZSG+6UXgCnFePtBE7e/ivXP/nRvUUl7UqNclvO3rpLqofPDAD8xiu2pOntjamqRy/RqZxs81oeVzwpCwfyA8A+8mLKFku9XfI0YnSKXnSYZ7ahSII+AwrqoMmEFKriAeVrqGM4O4Z+ADZIhjg3R6LtMpWuW0ERs5zunKVHdnnnMLNQqaUS0kyKkjE1aE98b8y9x9JYHH8aZXFMKO6JFMEvhucj3Wj0kY2D92HlHbE/9Vk77mD6srRZqmVEAZAAAAAElFTkSuQmCC'
);

During this step, your application will send a challenge to the device. The device will resolve this challenge by adding information and digitally signing the data.

The application will check the response from the device and get its credential ID. This ID will be used for further authentication requests.

Creation Request

To associate a device to a user, you need to instantiate a Webauthn\PublicKeyCredentialCreationOptions object.

It will need:

• The Relying Party

• The User data

• A challenge (random binary string)

• A list of supported public key parameters i.e. an algorithm list (at least one)

Optionally, you can customize the following parameters:

• A timeout

• A list of public key credential to exclude from the registration process

• The Authenticator Selection Criteria

• Attestation conveyance preference

• Extensions

Let’s see an example of the PublicKeyCredentialCreationOptions object. The following example is a possible Public Key Creation page for a dummy user "@cypher-Angel-3000".

<?php

declare(strict_types=1);

use Cose\Algorithms;
use Webauthn\AuthenticatorSelectionCriteria;
use Webauthn\PublicKeyCredentialDescriptor;
use Webauthn\PublicKeyCredentialCreationOptions;
use Webauthn\PublicKeyCredentialParameters;
use Webauthn\PublicKeyCredentialRpEntity;
use Webauthn\PublicKeyCredentialUserEntity;

// RP Entity i.e. the application
$rpEntity = PublicKeyCredentialRpEntity::create(
    'My Super Secured Application', //Name
    'foo.example.com',              //ID
    null                            //Icon
);

// User Entity
$userEntity = PublicKeyCredentialUserEntity::create(
    '@cypher-Angel-3000',                   //Name
    '123e4567-e89b-12d3-a456-426655440000', //ID
    'Mighty Mike',                          //Display name
    null                                    //Icon
);

// Challenge
$challenge = random_bytes(16);

// Public Key Credential Parameters
$publicKeyCredentialParametersList = [
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ES256),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ES256K),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ES384),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ES512),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_RS256),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_RS384),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_RS512),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_PS256),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_PS384),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_PS512),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ED256),
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ED512),
];

$publicKeyCredentialCreationOptions =
    PublicKeyCredentialCreationOptions::create(
        $rpEntity,
        $userEntity,
        $challenge,
        $publicKeyCredentialParametersList,
    )
;

You can change the default values for each and all options

$publicKeyCredentialCreationOptions =
    PublicKeyCredentialCreationOptions::create(
        $rpEntity,
        $userEntity,
        $challenge,
        $publicKeyCredentialParametersList,
    )
    ->setTimeout(30_000)
    ->excludeCredentials(...$excludedPublicKeyDescriptors)
    ->setAuthenticatorSelection(AuthenticatorSelectionCriteria::create())
    ->setAttestation(PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE)
;

Creation Response

What you receive must be a JSON object that looks like as follow:

{
    "id":"KVb8CnwDjpgAo[…]op61BTLaa0tczXvz4JrQ23usxVHA8QJZi3L9GZLsAtkcVvWObA",
    "type":"public-key",
    "rawId":"KVb8CnwDjpgAo[…]rQ23usxVHA8QJZi3L9GZLsAtkcVvWObA==",
    "response":{
        "clientDataJSON":"eyJjaGFsbGVuZ2UiOiJQbk1hVjBVTS[…]1iUkdHLUc4Y3BDSdGUifQ==",
        "attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSj[…]YcGhf"
    }
}

There are two steps to perform with this object:

• Load the data

• Verify it with the creation options set above

Data Loading

Now that all components are set, we can load the data we receive using the Public Key Credential Loader service (variable $publicKeyCredential).

<?php

declare(strict_types=1);

$data = '
{
    "id":"KVb8CnwDjpgAo[…]op61BTLaa0tczXvz4JrQ23usxVHA8QJZi3L9GZLsAtkcVvWObA",
    "type":"public-key",
    "rawId":"KVb8CnwDjpgAo[…]rQ23usxVHA8QJZi3L9GZLsAtkcVvWObA==",
    "response":{
        "clientDataJSON":"eyJjaGFsbGVuZ2UiOiJQbk1hVjBVTS[…]1iUkdHLUc4Y3BDSdGUifQ==",
        "attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSj[…]YcGhf"
    }
}';

$publicKeyCredential = $publicKeyCredentialLoader->load($data);

If no exception is thrown, you can go to the next step: the verification.

Response Verification

Now we have a fully loaded Public Key Credential object, but we need now to make sure that:

1. The authenticator response is of type AuthenticatorAttestationResponse

2. This response is valid.

The first step is easy to perform:

<?php

declare(strict_types=1);

use Webauthn\AuthenticatorAttestationResponse;

$authenticatorAttestationResponse = $publicKeyCredential->getResponse();
if (!$authenticatorAttestationResponse instanceof AuthenticatorAttestationResponse) {
    //e.g. process here with a redirection to the public key creation page. 
}

The second step is the verification against

• The Public Key Creation Options we created earlier,

• The HTTP request

The Authenticator Attestation Response Validator service (variable $authenticatorAttestationResponseValidator) will check everything for you: challenge, origin, attestation statement and much more.

<?php

declare(strict_types=1);

use Nyholm\Psr7\Factory\Psr17Factory;
use Nyholm\Psr7Server\ServerRequestCreator;

$psr17Factory = new Psr17Factory();
$creator = new ServerRequestCreator(
    $psr17Factory, // ServerRequestFactory
    $psr17Factory, // UriFactory
    $psr17Factory, // UploadedFileFactory
    $psr17Factory  // StreamFactory
);

$serverRequest = $creator->fromGlobals();

$publicKeyCredentialSource = $authenticatorAttestationResponseValidator->check(
    $authenticatorAttestationResponse,
    $publicKeyCredentialCreationOptions,
    $serverRequest
);

If no exception is thrown, the response is valid. You can store the Public Key Credential Source ($publicKeyCredentialSource) and associate it to the user entity.

By default, any type of authenticator can be used by your users and interact with you application. In certain circumstances, you may need to select specific authenticators e.g. when user verification is required.

The Webauthn API and this library allow you to define a set of options to disallow the registration of authenticators that do not fulfill with the conditions.

The class Webauthn\AuthenticatorSelectionCriteria is designed for this purpose. It is used when generating the Webauthn\PublicKeyCredentialCreationOptions object.

Available Criteria

Authenticator Attachment Modality

You can indicate if the authenticator must be attached to the client (platform authenticator i.e. it is usually not removable from the client device) or must be detached (roaming authenticator).

Possible values are:

• AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE: there is no requirement (default value),

• AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM: the authenticator must be attached,

• AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM: must be a roaming authenticator.

A primary use case for platform authenticators is to register a particular client device as a "trusted device" for future authentication. This gives the user the convenience benefit of not needing a roaming authenticator, e.g., the user will not have to dig around in their pocket for their key fob or phone.

Resident Key

With this criterion, a Public Key Credential Source will be stored in the authenticator, client or client device. Such storage requires an authenticator capable to store such a resident credential.

User Verification

Example

With this example, with require the user verification (PIN, fingerprint...), a resident key and an authenticator embedded onto a device. This is typacally what you will require for Windows Hello or Face ID authentication.

User Entity

A User Entity object represents a user in the Webauthn context. It has the following constraints:

• The user ID must be unique and must be a string,

• The username must be unique,

Hereafter a minimalist example of user entity:

As for the rp Entity, the User Entity may have an icon. This icon must also be secured.

User Entity Repository

The User Entity Repository manages all Webauthn users of your application.

There is no interface to implement or abstract class to extend so that it should be easy to integrate it in your application. You may already have a user repository.

It shall be noted that the Symfony bundle will need a user entity repository. This service shall implement Webauthn\Bundle\Repository\PublicKeyCredentialUserEntityRepository.

The methods required by the interface are as follow:

• public function findOneByUsername(string $username): ?PublicKeyCredentialUserEntity; This method tries to find out a user entity from the username.

• public function findOneByUserHandle(string $userHandle): ?PublicKeyCredentialUserEntity; This method tries to find out a user entity from the user handle i.e. the user ID.

• public function generateNextUserEntityId(): string; This method creates a user entity ID. Note that this method SHALL NOT save that ID. Its main purpose generate a unique ID that could be used for a user entity object at a later stage.

• public function saveUserEntity(PublicKeyCredentialUserEntity $userEntity): void; This method saves the user entity. If the user entity already exists, it should throw an exception.

The following example is totally fictive. We will add an extension input loc=true to the request option object.

<?php

declare(strict_types=1);

use Webauthn\AuthenticationExtensions\AuthenticationExtension;
use Webauthn\AuthenticationExtensions\AuthenticationExtensionsClientInputs;
use Webauthn\PublicKeyCredentialRequestOptions;

// Extensions
$extensions = AuthenticationExtensionsClientInputs::create()
    ->add(AuthenticationExtension::create('loc', true))
;

// Public Key Credential Request Options
$publicKeyCredentialRequestOptions = 
    PublicKeyCredentialRequestOptions::create(
        random_bytes(32) // Challenge
    )
    ->setExtensions($extensions)
;

Extension Output Checker

An Extension Output Checker will check the extension output.

It must implement the interface Webauthn\AuthenticationExtensions\ExtensionOutputChecker and throw an exception of type Webauthn\AuthenticationExtension\ExtensionOutputError in case of error.

In the previous example, we asked for the location of the device and we expect to receive geolocation data in the extension output.

<?php

declare(strict_types=1);

namespace Acme\Extension;

use Webauthn\AuthenticationExtensions\ExtensionOutputChecker;
use Webauthn\AuthenticationExtensions\ExtensionOutputError;

final class LocationExtensionOutputChecker
{
    public function check(AuthenticationExtensionsClientInputs $inputs, AuthenticationExtensionsClientOutputs $outputs): void
    {
        if (!$inputs->has('loc') || $inputs->get('loc') !== true) {
            return;
        }

        if (!$outputs->has('loc')) {
            //You may simply return but here we consider it is a mandatory extension output.
            throw new ExtensionOutputError(
                $inputs->get('loc'),
                'The location of the device is missing'
            );
        }

        $location = $outputs->get('loc');
        //... Proceed with the output e.g. by logging the location of the device
        // or verifying it is in a specific area.
    }
}

You can indicate the user verification requirements during the ceremonies by setting the value in your options.

Authenticator registration

$authenticatorSelectionCriteria = AuthenticatorSelectionCriteria::create()
    ->setUserVerification(AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_DISCOURAGED)
;

$publicKeyCredentialCreationOptions =
    PublicKeyCredentialCreationOptions::create(
        $rpEntity,
        $userEntity,
        $challenge,
        $publicKeyCredentialParametersList,
    )
    ->setAuthenticatorSelection($authenticatorSelectionCriteria)
;

User Authentication

// Public Key Credential Request Options
$publicKeyCredentialRequestOptions = PublicKeyCredentialRequestOptions::create(random_bytes(32))
    ->setUserVerification(
        PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_DISCOURAGED
    )
;

Receiving Attestation Statement

Attestation Metadata Repository

First of all, you must prepare an Attestation Metadata Repository. This service will manage all Metadata Statements depending on their sources (local storage or distant service).

Your Metadata Statement Repository must implement the interface Webauthn\MetadataService\MetadataStatementRepository that has two methods:

• findOneByAAGUID(string $aaguid): this method retrieves the MetadataStatement object with AAGUID. It shall return null in case of the absence of the MDS.

There are few steps to acheive. First, you have to add support classes for all attestation statement types into your Attestation Metatdata Manager.

<?php

declare(strict_types=1);

use Cose\Algorithm\Manager;
use Cose\Algorithm\Signature\ECDSA;
use Cose\Algorithm\Signature\EdDSA;
use Cose\Algorithm\Signature\RSA;
use Webauthn\AttestationStatement\AndroidSafetyNetAttestationStatementSupport;
use Webauthn\AttestationStatement\AndroidKeyAttestationStatementSupport;
use Webauthn\AttestationStatement\AttestationStatementSupportManager;
use Webauthn\AttestationStatement\FidoU2FAttestationStatementSupport;
use Webauthn\AttestationStatement\NoneAttestationStatementSupport;
use Webauthn\AttestationStatement\PackedAttestationStatementSupport;
use Webauthn\AttestationStatement\TPMAttestationStatementSupport;
use Webauthn\AttestationStatement\AppleAttestationStatementSupport;

// You normally already do this
$attestationStatementSupportManager = new AttestationStatementSupportManager();
$attestationStatementSupportManager->add(new NoneAttestationStatementSupport());

// Additional classes to add
$attestationStatementSupportManager->add(new FidoU2FAttestationStatementSupport());
$attestationStatementSupportManager->add(new AppleAttestationStatementSupport());
$attestationStatementSupportManager->add(new AndroidSafetyNetAttestationStatementSupport());
$attestationStatementSupportManager->add(new AndroidKeyAttestationStatementSupport(
    $psr18Client,         // Can be null if you don’t want to use the Google API
    $googleApiKey,        // Can be null if you don’t want to use the Google API
    $psr17RequestFactory  // Can be null if you don’t want to use the Google API
));
$attestationStatementSupportManager->add(new TPMAttestationStatementSupport());

// Cose Algorithm Manager
// The list of algorithm depends on the algorithm list you defined in your options
// You should use at least ES256 and RS256 algorithms that are widely used.
$coseAlgorithmManager = new Manager();
$coseAlgorithmManager->add(new ECDSA\ES256());
$coseAlgorithmManager->add(new RSA\RS256());

$attestationStatementSupportManager->add(new PackedAttestationStatementSupport($coseAlgorithmManager));

Next, you must inject the Metadata Statement Repository to your Attestation Object Loader.

$attestationObjectLoader = new AttestationObjectLoader($attestationStatementSupportManager, $metadataStatementRepository);

Credential Creation Options

By default, no Attestation Statement is asked to the Authenticators (type = none). To change this behavior, you just have to set the corresponding parameter in the Webauthn\PublicKeyCredentialCreationOptions object.

There are 3 conveyance modes available using PHP constants provided by the class Webauthn\PublicKeyCredentialCreationOptions:

• ATTESTATION_CONVEYANCE_PREFERENCE_NONE: the Relying Party is not interested in authenticator attestation (default)

• ATTESTATION_CONVEYANCE_PREFERENCE_INDIRECT: the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements.

• ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT: the Relying Party wants to receive the attestation statement as generated by the authenticator.

The Hard Way

<?php

use Webauthn\PublicKeyCredentialCreationOptions;

$publicKeyCredentialCreationOptions = new PublicKeyCredentialCreationOptions(
    $relyingParty
    $userEntity,
    $challenge,
    $pubKeyCredParams,
    $timeout, 
    $excludeCredentials,
    $authenticatorSelection,
    PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT
);

The following classes provide a setLogger function to pass your PSR-3 logger instance.

• Webauthn\AttestationStatement\AttestationObjectLoader

• Webauthn\AuthenticatorAssertionResponseValidator

• Webauthn\AuthenticatorAttestationResponseValidator

• Webauthn\PublicKeyCredentialLoader

• Webauthn\Counter\ThrowExceptionIfInvalid

With Webauthn, it is possible to authenticate a user without username. This behavior implies several constraints:

2. The user verification is required,

3. The list of allowed authenticators must be empty

Selection criteria for the registration of the authenticator:

$authenticatorSelectionCriteria = AuthenticatorSelectionCriteria::create()
    ->setUserVerification(AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED)
    ->setResidentKey(AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_REQUIRED)
;

$publicKeyCredentialCreationOptions =
    PublicKeyCredentialCreationOptions::create(
        $rpEntity,
        $userEntity,
        $challenge,
        $publicKeyCredentialParametersList,
    )
    ->setAuthenticatorSelection($authenticatorSelectionCriteria)
;

The Request Options:

// Public Key Credential Request Options

$publicKeyCredentialRequestOptions = PublicKeyCredentialRequestOptions::create(random_bytes(32))
    ->setUserVerification(
        PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_REQUIRED
    )
;

During this step, your application will send a challenge to the list of registered devices of the user. The security token will resolve this challenge by adding information and digitally signing the data.

Assertion Request

To perform a user authentication using a security device, you need to instantiate a Webauthn\PublicKeyCredentialRequestOptions object.

Let’s say you want to authenticate the user we used earlier. This options object will need:

• A challenge (random binary string)

• The list with the allowed credentials (may be an option in certain circumstances)

Optionally, you can customize the following parameters:

• A timeout

• The Relying Party ID i.e. your application domain

• The user verification requirement

• Extensions

The PublicKeyCredentialRequestOptions object is designed to be easily serialized into a JSON object. This will ease the integration into an HTML page or through an API endpoint.

Allowed Credentials

The user trying to authenticate must have registered at least one device. For this user, you have to get all Webauthn\PublicKeyCredentialDescriptor associated to his account.

// We gather all registered authenticators for this user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);

// We don’t need the Credential Sources, just the associated Descriptors
$allowedCredentials = array_map(
    static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
        return $credential->getPublicKeyCredentialDescriptor();
    },
    $registeredAuthenticators
);

Example

<?php

declare(strict_types=1);

use Webauthn\PublicKeyCredentialDescriptor;
use Webauthn\PublicKeyCredentialRequestOptions;
use Webauthn\PublicKeyCredentialSource;

// List of registered PublicKeyCredentialDescriptor classes associated to the user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
$allowedCredentials = array_map(
    static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
        return $credential->getPublicKeyCredentialDescriptor();
    },
    $registeredAuthenticators
);

// Public Key Credential Request Options
$publicKeyCredentialRequestOptions = 
    PublicKeyCredentialRequestOptions::create(
        random_bytes(32) // Challenge
    )
    ->allowCredentials(...$allowedCredentials)
;

User Verification

<?php

declare(strict_types=1);

use Webauthn\PublicKeyCredentialDescriptor;
use Webauthn\PublicKeyCredentialRequestOptions;
use Webauthn\PublicKeyCredentialSource;

// List of registered PublicKeyCredentialDescriptor classes associated to the user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
$allowedCredentials = array_map(
    static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
        return $credential->getPublicKeyCredentialDescriptor();
    },
    $registeredAuthenticators
);

// Public Key Credential Request Options
$publicKeyCredentialRequestOptions = 
    PublicKeyCredentialRequestOptions::create(
        random_bytes(32) // Challenge
    )
    ->setUserVerification(
        PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_REQUIRED
    )
;

Extensions

<?php

declare(strict_types=1);

use Webauthn\PublicKeyCredentialRequestOptions;

// List of registered PublicKeyCredentialDescriptor classes associated to the user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
$allowedCredentials = array_map(
    static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
        return $credential->getPublicKeyCredentialDescriptor();
    },
    $registeredAuthenticators
);

// Public Key Credential Request Options
$publicKeyCredentialRequestOptions = 
    PublicKeyCredentialRequestOptions::create(
        random_bytes(32) // Challenge
    )
    ->addExtension(
        AuthenticationExtension::create('loc', true),
        AuthenticationExtension::create('txAuthSimple', 'Please log in with a registered authenticator'),
    )
;

Response Handling

The way you receive this response is out of scope of this library. In the previous example, the data is part of the query string, but it can be done through a POST request body or a request header.

What you receive must be a JSON object that looks like as follows:

{
    "id":"KVb8CnwDjpgAo[…]op61BTLaa0tczXvz4JrQ23usxVHA8QJZi3L9GZLsAtkcVvWObA",
    "type":"public-key",
    "rawId":"KVb8CnwDjpgAo[…]rQ23usxVHA8QJZi3L9GZLsAtkcVvWObA==",
    "response":{
        "clientDataJSON":"eyJjaGFsbGVuZ2UiOiJQbk1hVjBVTS[…]1iUkdHLUc4Y3BDSdGUifQ==",
        "authenticatorData":"Y0EWbxTqi9hWTO[…]4aust69iUIzlwBfwABDw==",
        "signature":"MEQCIHpmdruQLs[…]5uwbtlPNOFM2oTusx2eg==",
        "userHandle":""
    }
}

There are two steps to perform with this object:

• Load the data

• Verify the loaded data against the assertion options set above

Data Loading

<?php

declare(strict_types=1);

$data = '
{
    "id":"KVb8CnwDjpgAo[…]op61BTLaa0tczXvz4JrQ23usxVHA8QJZi3L9GZLsAtkcVvWObA",
    "type":"public-key",
    "rawId":"KVb8CnwDjpgAo[…]rQ23usxVHA8QJZi3L9GZLsAtkcVvWObA==",
    "response":{
        "clientDataJSON":"eyJjaGFsbGVuZ2UiOiJQbk1hVjBVTS[…]1iUkdHLUc4Y3BDSdGUifQ==",
        "attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSj[…]YcGhf"
    }
}';

$publicKeyCredential = $publicKeyCredentialLoader->load($data);

Response Verification

Now we have a fully loaded Public Key Credential object, but we need now to make sure that:

1. The authenticator response is of type AuthenticatorAssertionResponse

2. This response is valid.

The first is easy to perform:

<?php

declare(strict_types=1);

use Webauthn\AuthenticatorAssertionResponse;

$authenticatorAssertionResponse = $publicKeyCredential->getResponse();
if (!$authenticatorAssertionResponse instanceof AuthenticatorAssertionResponse) {
    //e.g. process here with a redirection to the public key login/MFA page. 
}

The second step is the verification against the Public Key Assertion Options we created earlier.

The Authenticator Assertion Response Validator service (variable $authenticatorAssertionResponseValidator) will check everything for you.

<?php

declare(strict_types=1);

use Symfony\Component\HttpFoundation\Request;

$request = Request::createFromGlobals();

$userHandle = $userEntity->getId();
$publicKeyCredentialSource = $authenticatorAssertionResponseValidator->check(
    $publicKeyCredential->getRawId(),
    $authenticatorAssertionResponse,
    $publicKeyCredentialRequestOptions,
    $request,
    $userHandle
);

If no exception is thrown, the response is valid and you can continue the authentication of the user.

Secured Context

If your are working on a development environment, https may not be available but the context could be considered as secured. You can bypass the scheme verification by passing the list of rpIds you consider secured.

This framework provides a Symfony bundle that will help you to use the components within your Symfony application.

Installation

With Symfony Flex

Symfony Flex recipes are provided through a dedicated repository. It is highly recommended to add this repository before installing the bundle.

Then, you can install the bundle or the complete framework:

Without Symfony Flex

If you don't use Symfony Flex, you must register the bundle manually.

Repositories

The first steps are:

Firewall

User Entity

Your application certainly has a user repository. Good news: there is no need to modify it!

The User Entity Repository can be completely decoupled from the user entity used by your application.

This repository should be declared as a Symfony service and shall implement Webauthn\Bundle\Repository\PublicKeyCredentialUserEntityRepository.

Hereafter an example where the application User Repository is injected. This repository uses Doctrine and provides findOneBy* methods.

<?php

declare(strict_types=1);

namespace App\Repository;

use App\Entity\User;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Uid\Ulid;
use Webauthn\Bundle\Repository\PublicKeyCredentialUserEntityRepository as PublicKeyCredentialUserEntityRepositoryInterface;
use Webauthn\PublicKeyCredentialUserEntity;

final class PublicKeyCredentialUserEntityRepository implements PublicKeyCredentialUserEntityRepositoryInterface
{
    /**
     * The UserRepository $userRepository is the repository
     * that already exists in the application
     */
    public function __construct(private UserRepository $userRepository)
    {
    }

    /**
     * This method creates the next Webauthn User Entity ID
     * In this example, we use Ulid
     */
    public function generateNextUserEntityId(): string {
        return Ulid::generate();
    }

    /**
      * This method saves the user or does nothing if the user already exists.
      * It may throw an exception. Just adapt it on your needs
      */
    public function saveUserEntity(PublicKeyCredentialUserEntity $userEntity): void
    {
        /** @var User|null $user */
        $user = $this->userRepository->findOneBy([
            'id' => $userEntity->getId(),
        ]);
        if (!$user instanceof UserInterface) {
            return;
        }
        $user = new User(
            $userEntity->getId(),
            $userEntity->getUserIdentifier(),
            $userEntity->getDisplayName() // Or any other similar method your entity may have
        );
        $this->userRepository->save($user); // Custom method to be added in your repository
    }

    public function findOneByUsername(string $username): ?PublicKeyCredentialUserEntity
    {
        /** @var User|null $user */
        $user = $this->userRepository->findOneBy([
            'username' => $username,
        ]);

        return $this->getUserEntity($user);
    }

    public function findOneByUserHandle(string $userHandle): ?PublicKeyCredentialUserEntity
    {
        /** @var User|null $user */
        $user = $this->userRepository->findOneBy([
            'id' => $userHandle,
        ]);

        return $this->getUserEntity($user);
    }

    /**
     * Converts a Symfony User (if any) into a Webauthn User Entity
     */
    private function getUserEntity(null|User $user): ?PublicKeyCredentialUserEntity
    {
        if ($user === null) {
            return null;
        }

        return new PublicKeyCredentialUserEntity(
            $user->getUsername(),
            $user->getUserIdentifier(),
            $user->getDisplayName(),
            null
        );
    }
}

Security Bundle

At the end of the installation and configuration, you should have a config/packages/security.yaml file that looks like as follow:

User Authentication

To enable the user authentication, you just have to declare the webauthn authenticator if the appropriate firewall (here main).

As you have noticed, there is nothing to configure to have a fully functional firewall. The firewall routes are automatically created for you. They are namely:

• /login/options: to create the request options (POST only)

• /login: to submit the assertion response (POST only)

You should also ensure to allow anonymous users to contact those endpoints.

If you need, you can customize those endpoints (do not forget to allow anonymous access).

Request Profile

User Registration

The user registration can also managed by the firewall. It is disabled by default. If you want that feature, please enable it:

The firewall routes are automatically created for you. They are namely:

• /register/options: to create the creation options (POST only)

• /register: to submit the attestation response (POST only)

You should also ensure to allow anonymous users to contact those endpoints.

Authentication Attributes

The security token returned by the firewall sets some attributes depending on the assertion and the capabilities of the authenticator. The attributes are:

• IS_USER_PRESENT: the user was present during the authentication ceremony. This attribute is usually set to true by authenticators,

• IS_USER_VERIFIED: the user was verified by the authenticator. Verification may be performed by several means including biometrics ones (fingerprint, iris, facial recognition…).

You can then set constraints to the access controls. In the example below, the /admin path can be reached by users with the role ROLE_ADMIN and that have been verified during the ceremony.

Response Handlers

You can customize the responses returned by the firewall by using a custom handler. This could be useful when you want to return additional information to your application.

There are 4 types of responses and handlers:

• Request options: options returned during the authentication ceremony,

• Creation options: options returned during the registration ceremony,

• Authentication Success,

• Authentication Failure,

Request Options Handler

This handler is called when a client sends a valid POST request to the options_path during the authentication process. The default Request Options Handler is Webauthn\Bundle\Security\Handler\DefaultRequestOptionsHandler. It returns a JSON Response with the Public Key Credential Request Options objects in its body.

Your custom handler has to implement the interface Webauthn\Bundle\Security\Handler\RequestOptionsHandler and be declared as a service.

When done, you can set your new service in the firewall configuration:

Creation Options Handler

This handler is very similar to the previous one, except that it is called during the registration of a new user and has to implement the interface Webauthn\Bundle\Security\Handler\CreationOptionsHandler.

Authentication Success Handler

This handler is called when a client sends a valid assertion from the authenticator. The default handler is Webauthn\Bundle\Security\Handler\DefaultSuccessHandler.

Your custom handler has to implement the interface Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface and be declared as a container service.

When done, you can set your new service in the firewall configuration:

Authentication Failure Handler

This handler is called when an error occurred during the authentication process. The default handler is Webauthn\Bundle\Security\Handler\DefaultFailureHandler.

Your custom handler has to implement the interface Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface and be declared as a container service.

When done, you can set your new service in the firewall configuration:

The authenticators may have an internal counter. This feature is very helpful to detect cloned devices.

The default behaviour is to reject the assertions. This behaviour might cause some troubles as it could reject the real device whilst the fake one can continue to be used.

It is therefore required to go deeper in the protection of your application by logging the error and locking the associated account.

To do so , you have to create a custom Counter Checker and inject it to your Authenticator Assertion Response Validator. The checker must implement the interface Webauthn\Counter\CounterChecker.

<?php

declare(strict_types=1);


namespace App\Service;

use App\SecuritySystem;
use Assert\Assertion;
use Throwable;
use Webauthn\PublicKeyCredentialSource;

final class CustomCounterChecker implements CounterChecker
{
    private $securitySystem;

    public function __construct(SecuritySystem $securitySystem)
    {
        $this->securitySystem = $securitySystem ;
    }

    public function check(PublicKeyCredentialSource $publicKeyCredentialSource, int $currentCounter): void
    {
        try {
            Assertion::greaterThan($currentCounter, $publicKeyCredentialSource->getCounter(), 'Invalid counter.');
        } catch (Throwable $throwable) {
            $this->securitySystem->fakeDeviceDetected($publicKeyCredentialSource);
            throw $throwable;
        }
    }
}

The Hard Way

$authenticatorAssertionResponseValidator =
    AuthenticatorAssertionResponseValidator::create(
        $publicKeyCredentialSourceRepository,
        $tokenBindingHandler,
        $extensionOutputCheckerHandler,
        $coseAlgorithmManager
    )
    ->setCounterChecker(new CustomCounterChecker())
;

The Credential Source can be stored the way you want. As the Webauthn\PublicKeyCredentialSource class can be converted into JSON, it could be stored in a filesystem.

In general, Symfony applications use Doctrine. That is why the bundle provides a way to use Doctrine as storage system.

The Doctrine Entity

Hereafter an example of an entity.

This is the most simple example. Feel free to add custom fields that fits on your needs e.g. created_at or is_revoked.

<?php

declare(strict_types=1);

namespace App\Entity;

use App\Repository\PublicKeyCredentialSourceRepository;
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\GeneratedValue;
use Doctrine\ORM\Mapping\Id;
use Doctrine\ORM\Mapping\Table;
use Symfony\Component\Uid\AbstractUid;
use Symfony\Component\Uid\Ulid;
use Webauthn\PublicKeyCredentialSource as BasePublicKeyCredentialSource;
use Webauthn\TrustPath\TrustPath;

#[Table(name: "public_key_credential_sources")]
#[Entity(repositoryClass: PublicKeyCredentialSourceRepository::class)]
class PublicKeyCredentialSource extends BasePublicKeyCredentialSource
{
    #[Id]
    #[Column(type: "ulid", unique: true)]
    #[GeneratedValue(strategy: "NONE")]
    private string $id;

    public function __construct(
        string $publicKeyCredentialId,
        string $type,
        array $transports,
        string $attestationType,
        TrustPath $trustPath,
        AbstractUid $aaguid,
        string $credentialPublicKey,
        string $userHandle,
        int $counter
    )
    {
        $this->id = Ulid::generate();
        parent::__construct($publicKeyCredentialId, $type, $transports, $attestationType, $trustPath, $aaguid, $credentialPublicKey, $userHandle, $counter);
    }

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

The Repository

To ease the integration into your application, the bundle provides a concrete class that you can extend.

<?php

declare(strict_types=1);

namespace App\Repository;

use App\Entity\PublicKeyCredentialSource;
use Doctrine\Persistence\ManagerRegistry;
use Webauthn\Bundle\Repository\PublicKeyCredentialSourceRepository as BasePublicKeyCredentialSourceRepository;
use Webauthn\PublicKeyCredentialSource as BasePublicKeyCredentialSource;

final class PublicKeyCredentialSourceRepository extends BasePublicKeyCredentialSourceRepository
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, PublicKeyCredentialSource::class);
    }

    public function saveCredentialSource(BasePublicKeyCredentialSource $publicKeyCredentialSource, bool $flush = true): void
    {
        if (!$publicKeyCredentialSource instanceof PublicKeyCredentialSource) {
            $publicKeyCredentialSource = new PublicKeyCredentialSource(
                $publicKeyCredentialSource->getPublicKeyCredentialId(),
                $publicKeyCredentialSource->getType(),
                $publicKeyCredentialSource->getTransports(),
                $publicKeyCredentialSource->getAttestationType(),
                $publicKeyCredentialSource->getTrustPath(),
                $publicKeyCredentialSource->getAaguid(),
                $publicKeyCredentialSource->getCredentialPublicKey(),
                $publicKeyCredentialSource->getUserHandle(),
                $publicKeyCredentialSource->getCounter()
            );
        }
        parent::saveCredentialSource($publicKeyCredentialSource, $flush);
    }
}

This repository should be declared as a Symfony service.

services:
    App\Repository\PublicKeyCredentialSourceRepository: ~

Configuration

With Flex, you have a minimal configuration file installed through a Flex Recipe. You must set the repositories you have just created. You also have to modify the environment variables Relying_PARTY_ID and Relying_PARTY_NAME.

You may also need to adjust other parameters.

If you don’t use Flex, hereafter an example of configuration file:

webauthn:
#    logger: null # PSR-3 compatible logging service
    credential_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialSourceRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
    user_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialUserEntityRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
    token_binding_support_handler: 'Webauthn\TokenBinding\IgnoreTokenBindingHandler' # We ignore the token binding instructions by default
    creation_profiles: # Authenticator registration profiles
        default: # Unique name of the profile
            rp: # Relying Party information
                name: '%env(Relying_PARTY_NAME)%' # CHANGE THIS! or create the corresponding env variable
                id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
#                icon: null # Secured image (data:// scheme)
#            challenge_length: 32
#            timeout: 60000
#            authenticator_selection_criteria:
#                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE
#                require_resident_key: false
#                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
#            extensions:
#                loc: true
#            public_key_credential_parameters: # You should not change this list
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_EdDSA #Order is important. Preferred algorithms go first
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256K
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES512
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS512
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS512
#            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE
    request_profiles: # Authentication profiles
        default: # Unique name of the profile
            rp_id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
#            challenge_length: 32
#            timeout: 60000
#            user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
#            extensions:
#                loc: true
#    metadata:
#        enabled: false
#        mds_repository: 'App\Repository\MetadataStatementRepository'
#        status_report_repository: 'App\Repository\StatusReportRepository'
#        certificate_chain_checker: 'App\Security\CertificateChainChecker'

Creation Profiles

Relying Party (rp)

Challenge Length

By default, the length of the challenge is 32 bytes. You may need to select a smaller or higher length. This length can be configured for each profile:

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            challenge_length: 16

Timeout

The default timeout is set to 60 seconds (60 000 milliseconds). You can change this value as follows:

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            timeout: 30000

Authenticator Selection Criteria

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            authenticator_selection_criteria:
                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM
                require_resident_key: true
                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED

Public Key Credential Parameters

This option indicates the algorithms allowed for your application. By default, a large list of algorithms is defined, but you can add custom algorithms or reduce the list.

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            public_key_credential_parameters:
                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256

Attestation Conveyance

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT

Extensions

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            extensions:
                loc: true
                txAuthSimple: 'Please add your new authenticator'

Request Profiles

The parameters for the request profiles (i.e. the authentication) are very similar to the creation profiles. The only difference is that you don’t need all the detail of the Relying Party, but only its ID (i.e. its domain).

webauthn:
    request_profiles:
        acme:
            rp_id: 'example.com'

Please note that all parameters are optional. The following configuration is perfectly valid. However, and as mentioned above, the parameter id is highly recommended.

webauthn:
    request_profiles:
        acme: ~

The easiest way to manage the user verification requirements in your Symfony application is by using the creation and request profiles.

With Webauthn, it is possible to authenticate a user without username. This behavior implies several constraints:

2. The user verification is required,

3. The list of allowed authenticators must be empty

The bundle configuration should have a profile with the constraints listed above:

In some circumstances, you may need to register a new authenticator for a user e.g. when adding a new authenticator or when an administrator acts as another user to replace a lost device.

It is possible to perform this ceremony programmatically.

With a Symfony application, the fastest way for a user to register additional authenticators is to use the “controller” feature.

To add a new authenticator to a user, the bundle needs to know to whom it should be added. This can be:

• The current user itself e.g. from its own account

• An administrator acting for another user from a dashboard

For that purpose, a User Entity Guesser service should be created. This service shall implement the interface Webauthn\Bundle\Security\Guesser\UserEntityGuesser and its unique method findUserEntity.

You can directly use the Webauthn\Bundle\Security\Guesser\CurrentUserEntityGuesser as a Symfony service. It is designed to identify the user that is currently logged in.

In the example herafter where the current user is guessed using a controller parameter. This can be used when an administrator is adding an authenticator to another user account.

Now you just have to enable the feature and set the routes to your options and response controllers.

Now you can send requests to these new endpoints. For example, if you are using the Javascript library, the calls will look like as follow:

Creation Profile

Response Handlers

You can customize the responses returned by the controllers by using custom handlers. This could be useful when you want to return additional information to your application.

There are 3 types of responses and handlers:

• Creation options,

• Success,

• Failure.

Creation Options Handler

This handler is called during the registration of a authenticator and has to implement the interface Webauthn\Bundle\Security\Handler\CreationOptionsHandler.

Success Handler

This handler is called when a client sends a valid assertion from the authenticator. This handler shall implement the interface Webauthn\Bundle\Security\Handler\SuccessHandler. The default handler is Webauthn\Bundle\Service\DefaultSuccessHandler.

Failure Handler

This handler is called when an error occurred during the process. This handler shall implement the interface Webauthn\Bundle\Security\Handler\SuccessHandler. The default handler is Webauthn\Bundle\Service\DefaultFailureHandler.

Secured Context

If your are working on a development environment, https may not be available but the context could be considered as secured. You can bypass the scheme verification by passing the list of rpIds you consider secured.

To change the token binding behaviour, you can change the dedicated parameter in the bundle configuration.

Update the libraries

First of all, you have to make sure you are using the last v3.x release (v3.3.4 at the time of writing).

In addition, you have to make sure you are using PHP 8.1+.

Symfony Flex

If you use the Symfony bundle and Symfony Flex, please note that Flex Recipes are now provided through a dedicated server.

It is highly recommended to declare this server within your application composer.json file.

Spot deprecations

• The class Webauthn\Server is removed and there is no replacement.

Dependency Changes:

• Added:

  • symfony/http-client ^6.0

  • symfony/uid ^6.0

• Bumped:

  • spomky-labs/cbor-php minimal version is now ^3.0

  • spomky-labs/cbor-bundle minimal version is now ^3.0

  • symfony components minimal version is now ^6.0

  • symfony/psr-http-message-bridge minimal version is now ^2.0

  • thecodingmachine/safe minimal version is now ^2.0

• Removed:

  • sensio/framework-extra-bundle

  • ramsey/uuid

Update your Configuration Files

As the bundle sensio/framework-extra-bundle is not required anymore, the associated configuration may become useless if you do not use this bundle in your project.

The most notable changes are related to the Metadata Statement section

Upgrade the libraries

It is now time to upgrade the libraries. In your composer.json, change all web-auth/* dependencies from v3.x to v4.0. When done, execute composer update.

All Modifications In A Row

The authenticators may have an internal counter. This feature is very helpful to detect cloned devices.

The default behaviour is to reject the assertions. This might cause some troubles as it could reject the real device whilst the fake one can continue to be used. You may also want to log the error, warn administrators or lock the associated user account.

To do so , you have to create a custom Counter Checker and inject it to your Authenticator Assertion Response Validator. The checker must implement the interface Webauthn\Counter\CounterChecker.

The following example is fictive and show how to lock a user, log the error and throw an exception.

With Symfony, you must enable this feature to enable all the metadata types.

You can set the Google API key for the Android SafetyNet Attestation Statement support with the following configuration:

If you have some troubles when validating Android SafetyNet Attestation Statement, this may be caused by the leeway of the server clocks or the age of the statement. You can modify the default values as follows:

Credential Creation Options

By default, no Attestation Statement is asked to the Authenticators (type = none). To change this behavior, you just have to set the corresponding parameter in the Webauthn\PublicKeyCredentialCreationOptions object.

There are 3 conveyance modes available using PHP constants provided by the class Webauthn\PublicKeyCredentialCreationOptions:

• ATTESTATION_CONVEYANCE_PREFERENCE_NONE: the Relying Party is not interested in authenticator attestation (default)

• ATTESTATION_CONVEYANCE_PREFERENCE_INDIRECT: the Relying Party prefers an attestation conveyance yielding verifiable attestation statements, but allows the client to decide how to obtain such attestation statements.

• ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT: the Relying Party wants to receive the attestation statement as generated by the authenticator.

The Symfony Way

Extension Output Checker

An Extension Output Checker will check the extension output.

It must implement the interface Webauthn\AuthenticationExtensions\ExtensionOutputChecker and throw an exception of type Webauthn\AuthenticationExtension\ExtensionOutputError in case of error.

In the previous example, we asked for the location of the device and we expect to receive geolocation data in the extension output.

The Symfony Way

The easiest way to manage that is by using the creation and request profiles.

By default, any type of authenticator can be used by your users and interact with you application. In certain circumstances, you may need to select specific authenticators e.g. when user verification is required.

The Webauthn API and this library allow you to define a set of options to disallow the registration of authenticators that do not fulfill with the conditions.

The class Webauthn\AuthenticatorSelectionCriteria is designed for this purpose. It is used when generating the Webauthn\PublicKeyCredentialCreationOptions object.

Available Criteria

Authenticator Attachment Modality

You can indicate if the authenticator must be attached to the client (platform authenticator i.e. it is usually not removable from the client device) or must be detached (roaming authenticator).

Possible values are:

• AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE: there is no requirement (default value),

• AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM: the authenticator must be attached,

• AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM: must be a roaming authenticator.

A primary use case for platform authenticators is to register a particular client device as a "trusted device" for future authentication. This gives the user the convenience benefit of not needing a roaming authenticator, e.g., the user will not have to dig around in their pocket for their key fob or phone.

Resident Key

When this criterion is set to true, a Public Key Credential Source will be stored in the authenticator, client or client device. Such storage requires an authenticator capable to store such a resident credential.