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...
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.
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.
Disclaimer: you should not ask for the Attestation Statement unless 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.
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.
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.
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:
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
aka the application you are interacting with
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
.
This $rpEntity
object will be useful for the next steps.
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.
Even if it is optional, we highly recommend setting the application ID
The rp
ID shall be the domain of the application without the scheme, userinfo, port, path, user…. IP addresses are not allowed either.
Allowed: www.sub.domain.com
, sub.domain.com
, domain.com
Not allowed:
www.sub.domain.com:1337
, https://domain.com:443
, sub.domain.com/index
, https://user:password@www.domain.com
.
12.65.76.43 or [2001:db8:85a3:8d3:1319:8a2e:370:7348]
The domain localhost
can be used if the browser considers the context is safe (especially the IP address corresponds to a local address)
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
.
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.
The Webauthn specification does not set any limit for the length of the third argument.
The icon may be ignored by browsers, especially if its length is greater than 128 bytes.