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...
Loading...
Loading...
Loading...
Loading...
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 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.
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.
install composer: curl -s http://getcomposer.org/installer | php
install dependencies: php composer.phar install
run tests: vendor/bin/phpunit
Seamless Integration with PHP Applications: Our Webauthn Documentation and Tutorials
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.
What is an authenticator?
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.
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.
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.
This page is about an advanced feature. You can skip it if you are new with Webauthn
Disclaimer: you should not ask for the Attestation Statement unless you want to play with it or you are working on an application that requires a high level of trust (e.g. Banking/Financial Company, Government Agency...).
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.
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.
The FIDO Alliance Metadata Service provides a limited number of Metadata Statements. It is mandatory to get the statement from the manufacturer of your authenticators otherwise the Attestation Statement won't be verified and the Attestation Ceremony will fail.
Prove to me who you claim to be!
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
Adoption by web browsers
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:
Authenticator details and how to manage them
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
...
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.
Whatever database you use (MySQL, pgSQL…), it is not necessary to create relationships between your users and the Credential Sources.
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.
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.
Whatever database you use (MySQL, pgSQL…), it is not necessary to create relationships between your users and the Credential Sources.
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.
Note that is mandatory to use the HTTPS scheme to use Webauthn otherwise it will not work. This is also mandatory for localhost
.