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.

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 the W3C dedicated page.

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 section 5.2.2 “Web Authentication Assertion” shows an object named AuthenticatorAssertionResponse that extends AuthenticatorResponse with the following properties:

• authenticatorData

• signature

• userHandle

  You will find EXACTLY the same structure 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.

If you really love that project, and the work I have done or if you want I prioritize your issues, then you can help me out for a couple of🍻 or more!

Contributing

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

If you feel comfortable writing code, you could try to fix opened issues where help is wanted or those that are easy to fix.

Do not forget to follow these best practices.

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.

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

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.

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

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

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

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

Upon completion, you'll have the capability to register authenticators and verify the identity of your users.