Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
How to install the library or the Symfony bundle?
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:
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.
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.
Overview of the framework
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.
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.
Attestation Types
Empty
Basic
Self
Private CA
Anonymization CA
Note that Elliptic Curve Direct Anonymous Attestation (ECDAA) is deprecated and not supported
Attestation Formats
FIDO U2F
Packed
TPM
Android Key
Android Safetynet
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
The Token Binding support feature is now deprecated as not part of the latest specification version
The framework is already compatible with all authenticators.
The compliance of the framework is ensured by running unit and functional tests during its development.
It is also tested using the official FIDO Alliance testing tools. The status of the compliance tests are reported in this issue. At the time of writing (January 2023, all features and algorithms are supported and 100% of the tests pass.
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!
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.
If you think you have found a security issue, DO NOT open an issue. You MUST submit your issue here.
Registration and Authentication process overview
In the Webauthn context, there are two ceremonies:
The attestation ceremony
The assertion ceremony: it is used for the authentication of a user.
For both ceremonies, there are two steps to perform:
The creation of options: these options are sent to the authenticator and indicate what to do and how.
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…).
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.
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.
You have just found a bug?
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 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).
To contribute use Pull Requests, please, write commit messages that make sense, and rebase your branch before submitting your PR.
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.
install composer: curl -s http://getcomposer.org/installer | php
install dependencies: php composer.phar install
run tests: vendor/bin/simple-phpunit
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.
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.
The timeout default value is set to null
. If you want to set a value, pleaase read the following recommended behavior showed in the specification:
If the user verification is discouraged
, timeout should be between 30 and 180 seconds
If the user verification is preferred
or required
, the range is 300 to 600 seconds (5 to 10 minutes)
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.
For usernameless authentication, please read the dedicated page. In this case no Public Key Credential Descriptors should be passed to the the options.
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.
Please refer to the Extension page to know how to manage authentication extensions.
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:
There are two steps to perform with this object:
Load the data
Verify the loaded data against the assertion options set above
This step is exactly the same as the one described in Public Key Credential Creation process.
Now we have a fully loaded Public Key Credential object, but we need now to make sure that:
The authenticator response is of type AuthenticatorAssertionResponse
This response is valid.
The first is easy to perform:
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.
If no exception is thrown, the response is valid and you can continue the authentication of the user.
The Public Key Credential Source returned allows you to know which device was used by the user.
It's all about users
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:
The username can be composed of any displayable characters, including emojis. Username "😝🥰😔" is perfectly valid.
Developers should not add rules that prevent users from choosing the username they want.
For privacy reasons, it is not recommended using the e-mail as username.
As for the rp
Entity, the User Entity may have an icon. This icon must also be secured.
The Webauthn specification does not set any limit for the length of the icon.
The icon may be ignored by browsers, especially if its length is greater than 128 bytes.
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.
Whatever database you use (MySQL, pgSQL…), it is not necessary to create relationships between your users and the Credential Sources.
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.
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.
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.
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.
A resident key shall be created you want to authenticate users without username.
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.