Welcome to WebAuthn, the solution for strong authentication on the web. With WebAuthn, you can offer your users a secure, simple, and convenient authentication experience that seamlessly integrates with your PHP or Symfony application.

At Spomky-Labs, we are committed to making the web safer for all users. We provide free, libre, and open-source libraries and a Symfony bundle to help you implement strong authentication solutions for your websites and applications.

WebAuthn is an open-source technology developed by the World Wide Web Consortium (W3C) and is compatible with all modern web browsers. With WebAuthn and PHP, you can offer your users secure authentication without requiring them to remember complex passwords or provide sensitive personal information.

WebAuthn is supported by the FIDO Alliance, an organization working to promote open and interoperable strong authentication standards. You can learn more about the FIDO Alliance by visiting their website at https://fidoalliance.org/.

Explore our documentation to learn more about WebAuthn and how it can help you implement strong authentication in your PHP or Symfony application.

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 follow the PSR-12 for coding standards.

• You MUST use the PSR-20 to get the time.

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

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

• You SHOULD write documentation.

• You MAY follow the PSR-5 and PSR-19.

We use the following branching workflow:

• Each minor version has a dedicated branch (e.g. 1.1.x, 1.2.x, 2.0.x, 2.1.x…)

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

• Please select the correct branch when submitting a PR

  • If it is a bug fix, please use the version first major release (1.0.x, 2.0.x, 3.0.x...)

  • If it is a new feature, please use the last minor release

To contribute use Pull Requests, please, write commit messages that make sense, and rebase your branch before submitting your PR.

Run test suite

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

• install dependencies: php composer.phar install

• run tests: vendor/bin/phpunit

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+

For more information and limitation on these browsers, please have a look at the following page: https://caniuse.com/#feat=webauthn

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

If you use Symfony Framework, you may be interested in the bundle and, optionally, the Stimulus component.

composer require web-auth/webauthn-symfony-bundle web-auth/webauthn-stimulus

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?

web-auth/cose-lib contains several cipher algorithms and COSE key support to verify the digital signatures sent by the authenticators during the creation and authentication ceremonies. These algorithms are compliant with the RFC8152. This library can be used by any other PHP projects. At the moment only signature algorithms are available, but it is planned to add encryption algorithms.

web-auth/metadata-service provides classes to support the Fido Alliance Metadata Service. If you plan to use Attestation Statements during the creation ceremony, this service is mandatory. Please note that Attestation Statements decreases the user privacy as they may leak data that allow to identify a specific user. The use of Attestation Statements and this service are generally not recommended unless you REALLY need this information. This library can also be used by any other PHP projects.

Credential Source Class

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:

• The credential ID,

• The public key,

• The credential type (public_key),

• The transports (USB, NFC, BLE, internal),

• The attestation type,

• The trust path,

• The authenticator AAGUID,

• The user handle (i.e. the user ID)

• The authenticator counter,

• Other UI data

• ...

Credential Source Repository

Since 4.6.0 and except if you use the Symfony bundle, there is no interface to implement or abstract class to extend so that it should be easy to integrate it in your application.

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 you have a web application that can be reached at https://m.my-app.com (for mobiles) and https://my-app.com or https://www.my-app.com (for other devices), your Relying Party ID should be my-app.com.

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'
);

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.

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.

There are several possible sources to get these Metadata Statements. The main source is the FIDO Alliance Metadata Service that allows fetching statements on-demand, but some of them may be provided by other means.

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

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

We highly recommend the use of @simplewebauthn/browser. This library provides lots of easy and useful features and it fully compliant with the specification.

If you use the Symfony UX, you may be interested in the Stimulus Controller.

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 or creation ceremony: associates an authenticator to a user account

• The assertion ceremony or request ceremony: 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 ceremony

This ceremony aims at registering an authenticator. It can be used during the creation of a new user account or when an existing user wants to add an additional authenticator.

Assertion ceremony

This ceremony aims at authenticating a user. The user will be asked to interact with one of its authenticators. Additional authentication means, such as PIN code or fingerprint, may be required.

To set up a Webauthn server, you'll require components from two main categories:

• : serivces required to load the data and convert into DTO or other objects

• : services required to verify the input data and return the result of this validation

Upon completion, you'll have the capability to and .

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.

Standard extensions are usually listed in the dedicated IANA Registry available at

User Entity Class

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

Except if you use the Symfony bundle, 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.

The loaded data needs to be verified. The library will perform several actions to make sure the input you received is valid. This verification process is performed by a Ceremony Step Manager (CSM). The Webauthn Specification distinguish two types of ceremonies.

Ceremony Step Manager Factory

To facilitate the creation of the CSM, a default factory is included. This factory requires no external services to function.

These CSM services are meant to be used by Response Validators. On a similar way, there are two types of validators:

• Authenticator Attestation Response Validator: used during the creation ceremony

• Authenticator Assertion Response Validator: used during the request ceremony

Response Validators

In general, the data you receive is an encoded JSON object. The library provides utilities to convert the string into objects.

To do so, you will need an Attestation Statement Support Manager and a Serializer.

Attestation Statement Support Manager

Authenticator Responses may contain an Attestation Statement. This attestation holds 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

The following attestation types are supported. Note that you should only use the none one unless you have specific needs described in the dedicated page.

• none: no attestation is provided.

• fido-u2f: for non-FIDO2 compatible devices (old FIDO / 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 (deprecated).

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

• apple: for Apple devices

<?php

declare(strict_types=1);

use Webauthn\AttestationStatement\AttestationStatementSupportManager;
use Webauthn\AttestationStatement\NoneAttestationStatementSupport;

// The manager will receive data to load and select the appropriate 
$attestationStatementSupportManager = AttestationStatementSupportManager::create();
$attestationStatementSupportManager->add(NoneAttestationStatementSupport::create());

The Serializer

To convert Authenticator Responses from the encoded string to an object, you will need a Serializer. It only needs the Attestation Statement Support Manager created above.

<?php

declare(strict_types=1);

use Webauthn\Denormalizer\WebauthnSerializerFactory;

$factory = new WebauthnSerializerFactory($attestationStatementSupportManager);
$serializer = $factory->create();

Loding Data

In general, the data you receive looks like as follows.

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

<?php

declare(strict_types=1);

use Webauthn\PublicKeyCredential;

// $data corresponds to the JSON object showed above
$publicKeyCredential = $serializer->deserialize(
    $data,
    PublicKeyCredential::class,
    'json'
);

If the data is correctly loaded, the variable $publicKeyCredential will be an instance of Webauthn\PublicKeyCredential. An exception is thrown in case of an error.

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

Please refer to this page.

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.

use Webauthn\AuthenticatorSelectionCriteria;
use Webauthn\PublicKeyCredentialCreationOptions;

$authenticatorSelectionCriteria = AuthenticatorSelectionCriteria::create(
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED,
    residentKey:AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_REQUIRED,
    authenticatorAttachment: AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM
);

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

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

1. During the registration of the authenticator, a Resident Key must have been asked,

2. The user verification is required,

3. The list of allowed authenticators must be empty

Selection criteria for the registration of the authenticator:

use Webauthn\AuthenticatorSelectionCriteria;
use Webauthn\PublicKeyCredentialCreationOptions;


$authenticatorSelectionCriteria = AuthenticatorSelectionCriteria::create(
    userVerification: AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED,
    residentKey: AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_REQUIRED,
);

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

The Request Options:

// Public Key Credential Request Options

use Webauthn\PublicKeyCredentialRequestOptions;

$publicKeyCredentialRequestOptions = PublicKeyCredentialRequestOptions::create(
    random_bytes(32),
    userVerification: PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_REQUIRED
);

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 Webauthn\PublicKeyCredentialCreationOptions;
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);

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

The options object can be converted into JSON and sent to the authenticator using the API.

$jsonObject = json_encode($publicKeyCredentialCreationOptions);

You can change the default values for each and all options

$publicKeyCredentialCreationOptions =
    PublicKeyCredentialCreationOptions::create(
        $rpEntity,
        $userEntity,
        $challenge,
        pubKeyCredParams: $publicKeyCredentialParametersList,
        authenticatorSelection: AuthenticatorSelectionCriteria::create(),
        attestation: PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE,
        excludeCredentials: $excludedPublicKeyDescriptors,
        timeout: 30_000,
    )
;

Public Key Credential Parameters

The argument pubKeyCredParams contains a list of Webauthn\PublicKeyCredentialParameters objects that refer to COSE algorithms. The authenticators must use one of the algorithms in this list, respecting the order of preference on this list.

An empty list corresponds to the default algorithms that are ES256 and RS256 (in this order). Those two algorithms are required by the specification.

use Cose\Algorithms;
use Webauthn\PublicKeyCredentialParameters;

$publicKeyCredentialParametersList = [
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ES256K), // More interesting algorithm
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ES256),  //      ||
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_RS256),  //      || 
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_PS256),  //      \/
    PublicKeyCredentialParameters::create('public-key', Algorithms::COSE_ALGORITHM_ED256),  // Less interesting algorithm
];

Authenticator Selection

Please read detail on this page.

Attestation

Please read detail on this page.

Exclude Credentials

When the user already registered authenticators, you can pass a list of Webauthn\PublicKeyCredentialDescriptor objects as argument to avoid registering multiple times the same authenticator.

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 Serializer (variable $serializer).

<?php

declare(strict_types=1);

use Webauthn\PublicKeyCredential;

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

$publicKeyCredential = $serializer->deserialize(
    $data,
    PublicKeyCredential::class,
    'json'
);

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;

if (!$publicKeyCredential->response 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 URI host

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

$publicKeyCredentialSource = $authenticatorAttestationResponseValidator->check(
    $authenticatorAttestationResponse,
    $publicKeyCredentialCreationOptions,
    'my-application.com'
);

If no exception is thrown, the response is valid. You can store the Public Key Credential Source ($publicKeyCredentialSource).

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.

use Webauthn\PublicKeyCredentialSource;

// We gather all registered authenticators for this user
// $publicKeyCredentialSourceRepository corresponds to your own service
// The purpose of the fictive method findAllForUserEntity is to return all credential source objects
// registered by the 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

Eligible authenticators are filtered and only capable of satisfying this requirement will interact with the user. Please refer to the User Verification page for all possible values.

<?php

declare(strict_types=1);

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

// Public Key Credential Request Options
$publicKeyCredentialRequestOptions =
    PublicKeyCredentialRequestOptions::create(
        random_bytes(32), // Challenge
        userVerification: PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_REQUIRED
    )
;

Extensions

Please refer to the Extension page to know how to manage authentication extensions.

<?php

declare(strict_types=1);

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

// Public Key Credential Request Options
$publicKeyCredentialRequestOptions =
    PublicKeyCredentialRequestOptions::create(
        random_bytes(32), // Challenge
        extensions: AuthenticationExtensionsClientInputs::create([
            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

This step is exactly the same as the one described in Public Key Credential Creation process.

<?php

declare(strict_types=1);

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

$publicKeyCredential = $serializer->deserialize($data, PublicKeyCredential::class, 'json');

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;

if (!$publicKeyCredential->response 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);

$publicKeyCredentialSource = $publicKeyCredentialSourceRepository->findOneByCredentialId(
    $publicKeyCredential->rawId
);
if ($publicKeyCredentialSource === null) {
   // Throw an exception if the credential is not found.
   // It can also be rejected depending on your security policy (e.g. disabled by the user because of loss)
}

$publicKeyCredentialSource = $authenticatorAssertionResponseValidator->check(
    $publicKeyCredentialSource,
    $authenticatorAssertionResponse,
    $publicKeyCredentialRequestOptions,
    'my-application.com',
    $userEntity?->id // Should be `null` if the user entity is not know before this step
);

// Optional, but highly recommended, you can save the credential source as it may be modified
// during the verification process (counter may be higher).
$publicKeyCredentialSourceRepository->saveCredential($publicKeyCredentialSource);

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

If you have troubles during the development of your application or if you want to keep track of every critical/error messages in production, you can use a .

Several classes implement the interface Webauthn\MetadataService\CanLogData. This interface allows setting a PSR-3 logger instance.

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

Authenticator registration

User Authentication

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

The following algorithms are required in most situations:

The complete list of supported algorithms:

The algorithm manager can be injected to your Ceremony Step Manager Factory.

Attestation Statement Support Manager

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

Metadata Statement Repository

Then, you must prepare an Metadata Statement 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 only one method:

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

Status Report Repository

To prevent the use of rogue MDS or deprecated by the manufacturers, Status Reports may be used. The Status Report Repository is a simple service that implements the interface Webauthn\MetadataService\StatusReportRepository with a unique method:

• findStatusReportsByAAGUID(string $aaguid): this method returns a list of Status Reports for the given AAGUID.

The verification's success or failure depends on the state reported in the most recent Status Report.

Certificate Chain Validator

When an attestation statement is received, a certificate chain is constructed. This chain combines certificates from the Metadata Service (MDS), which are trusted, with those provided by the authenticator, which are untrusted.

Ceremony Step Manager Factory

Requesting Attestation Statement

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.

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.

The complete specification can be found on .

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.

As an example, the shows an object named AuthenticatorAssertionResponse that extends AuthenticatorResponse with the following properties:

• authenticatorData

• signature

• userHandle

  You will find in the PHP class provided by the library.

Supported features

• Attestation Types

  • Empty

  • Basic

  • Self

  • Private CA

  • Anonymization CA

• Attestation Formats

  • FIDO U2F

  • Packed

  • TPM

  • Android Key

  • Android Safetynet (deprecated)

  • Apple

• 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

As of January 2023, our framework supports every authenticator with full feature and algorithm support, achieving a 100% success rate across all tests. Official FIDO Alliance testing tools have validated its compliance.

We ensure continuous conformity through rigorous unit and functional testing throughout the development process.

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.

Security Bundle

To authenticate or register your users with Symfony, the best and easiest way is to use the Security Bundle. First, install that bundle and follow the instructions given by the official documentation.

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

security:
    providers:
        default:
            id: App\Security\UserProvider
    firewalls:
        main:
            logout:
                path: 'logout'
            ...

User Authentication

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

security:
    providers:
        default:
            id: App\Security\UserProvider
    firewalls:
        main:
            webauthn: ~
            logout:
                path: '/logout'
    access_control:
        - { path: ^/login,  roles: PUBLIC_ACCESS, requires_channel: 'https'}
        - { path: ^/logout,  roles: PUBLIC_ACCESS}

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)

If you need, you can customize those endpoints.

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    routes:
                        options_path: '/assertion/options'
                        result_path: '/assertion/result'

    access_control:
        - { path: ^/assertion,  roles: PUBLIC_ACCESS, requires_channel: 'https'}

Request Profile

By default, the default profile is used (see request_profiles in the Configuration References). You may have created a request profile in the bundle configuration. You can use this profile instead of the default one.

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    profile: 'acme'

User Registration

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

security:
    firewalls:
        main:
            webauthn:
                registration:
                    enabled: true

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.

security:
    access_control:
        - { path: ^/register,  roles: PUBLIC_ACCESS}

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.

security:
    access_control:
        - { path: ^/admin,  roles: [ROLE_ADMIN, IS_USER_VERIFIED]}

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:

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    options_handler: 'App\Handler\MyCustomRequestOptionsHandler'

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.

ecurity:
    firewalls:
        main:
            webauthn:
                registration:
                    options_handler: 'App\Handler\MyCustomRequestOptionsHandler'

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:

security:
    firewalls:
        main:
            webauthn:
                success_handler: 'App\Handler\MyCustomAuthenticationSuccessHandler'

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:

security:
    firewalls:
        main:
            webauthn:
                failure_handler: 'App\Handler\MyCustomAuthenticationFailureHandler'

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\PublicKeyCredentialUserEntityRepositoryInterface.

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 Webauthn\Bundle\Repository\PublicKeyCredentialUserEntityRepositoryInterface;
use Webauthn\PublicKeyCredentialUserEntity;

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

    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
        );
    }
}

Registration Capability

By default, the User Entity Repository is not able to register any user account. You can add this behaviour by implementing the following interfaces:

• Webauthn\Bundle\Repository\CanRegisterUserEntity

• Webauthn\Bundle\Repository\CanGenerateUserEntity

If you have troubles during the development of your application or if you want to keep track of every critical/error messages in production, you can use a PSR-3 compatible logger.

webauthn:
    logger: App\Service\MyPsr3Logger

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 Counter Checker service can be injected to your Ceremony Step Manager Factory.

<?php

declare(strict_types=1);

use Webauthn\CeremonyStep\CeremonyStepManagerFactory;

$csmFactory = new CeremonyStepManagerFactory();
$csmFactory->setCounterChecker($customCounterChecker);

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

Installation

With Symfony Flex

composer require web-auth/webauthn-symfony-bundle

Without Symfony Flex

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

<?php

return [
    //...
    Webauthn\Bundle\WebauthnBundle::class => ['all' => true],
];

<?php

declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes) {
    $routes->import('.', 'webauthn');
};

Repositories

The first steps are:

• The creation of your Credential Source repository

• The creation of your User Entity repository.

You may also want to configure the other options offered by the bundle. Please refer to the configuration references.

Firewall

Now you have a fully configured bundle, you can protect your routes and manage the user registration and authenticatin through the Symfony Firewall.

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.

<?php

declare(strict_types=1);

use Webauthn\CeremonyStep\CeremonyStepManagerFactory;

$csmFactory = new CeremonyStepManagerFactory();
$csmFactory->setSecuredRelyingPartyId(['secure.localhost']);

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\AuthenticationExtensions;
use Webauthn\PublicKeyCredentialRequestOptions;

// Extensions
$extensions = AuthenticationExtensions::create([
    AuthenticationExtension::create('loc', true)
]);

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

Extension Output Checker

An Extension Output Checker (EOC) 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 implements ExtensionOutputChecker
{
    public function check(AuthenticationExtensions $inputs, AuthenticationExtensions $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.
    }
}

Extension Output Checker Handler

You can create as many EOC as needed. These services can be managed by a handler that will be injected to the Ceremony Step Manager Factory. Extensions will be automatically verified during the validation steps.

<?php

declare(strict_types=1);

namespace Acme\Extension;

use Webauthn\AuthenticationExtensions\ExtensionOutputCheckerHandler;
use Webauthn\CeremonyStep\CeremonyStepManagerFactory;

$eocHandler = ExtensionOutputCheckerHandler::create();
$eocHander->add(new LocationExtensionOutputChecker());
// Add more EOC if needed.

$csmFactory = new CeremonyStepManagerFactory();
$csmFactory->setExtensionOutputCheckerHandler($eocHander);