Download the PHP package simplesamlphp/simplesamlphp-module-webauthn without Composer
On this page you can find all versions of the php package simplesamlphp/simplesamlphp-module-webauthn. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download simplesamlphp/simplesamlphp-module-webauthn
More information about simplesamlphp/simplesamlphp-module-webauthn
Files in simplesamlphp/simplesamlphp-module-webauthn
Package simplesamlphp-module-webauthn
Short Description A PHP implementation of a FIDO2 / WebAuthn authentication agent
License LGPL-2.1-or-later
Informations about the package simplesamlphp-module-webauthn
WebAuthn as Second Factor module
The module is implemented as an Authentication Processing Filter. That means it can be configured in the global config.php file or the SP remote or IdP hosted metadata.
Installation
You can install this module with composer:
If you are using PHP 7, you also need to install either the GMP extension (recommended) or the BCMath extension.
How to setup the webauthn module as a second-factor (an authprocfilter)
You need to enable the module's authprocfilter at a priority level so that it takes place AFTER the first-factor authentication. E.g. at 100 and if standalone registration and name2oid are used together, then the WebAuthn auth proc filter has to run after name2oid.
The authproc filter takes a number of optional parameter that steer which users will be forced into 2FA.
Then you need to copy config-templates/module_webauthn.php to your config directory and adjust settings accordingly. See the file for parameters description.
How to set up (pure) Passwordless authentication
In passwordless mode, the module provides an AuthSource, to be configured as usual in simpleSAMLphp's config/authsources.php
Users' FIDO2 Keys need to be registered with the "Passwordless" checkbox set - this triggers the mandatory registration with a second factor intrinsic to the key (fingerprint, face recognition, transaction PIN, etc. ).
This authsource takes little configuration because authentications happen before the username is known - so no user-specific configuration is possible.
The authsource takes the following parameters in authsources.php:
How to set up simultaneous Passwordless and traditional two-factor
In this mode, the authentication prompt simultaneously allows for either triggering a Passwordless auth, or to enter a username/password as traditional first-factor.
The configuration is almost identical to Passwordless above, but requires one extra required configuration parameter: the authsource that should be used to validate the username/password, if supplied by the user.
The authsource takes the following parameters in authsources.php:
Using storage
The database schema sets itself up on first use automatically. The schema can be found in the sources at src/WebAuthN/Store/Database.php (__construct).
If you want to trim down permissions for the database user, here is the minimal set of required permissions:
The webauthn:Database
backend storage has the following options:
class
: Must be set to webauthn:Database
.
database.dsn
: Data Source Name must comply to the syntax for the PHP PDO layer.
database.username
: Username for the database user to be used for the connection.
database.password
: Password for the database user used for the connection.
timeout
: The number of seconds to wait for a connection to the database server. This option is optional. If unset, it uses the default from the database-driver.
Example config using PostgreSQL database:
Example config using MySQL database:
Options
Options of auth proc filter
default_enable
: Should WebAuthn be enabled by default for all users? If not, users need to be white-listed in the database - other users simply pass through the filter without being subjected to 2FA. Defaults to "disabled by default" === false
force
: This parameter is used only if "use_database" is false. If the value of "force" is true then we trigger WebAuthn only if "attrib_toggle" from the user is not empty. If the value of "force" is false then we switch the value of "default_enable" only if "attrib_toggle" from the user is not empty. Default value is true.
attrib_toggle
: This parameter stores the name of the attribute that is sent with user and which determines whether to trigger WebAuthn. Default value is 'toggle'.
use_database
: This parameter determines if the database will be used to check whether to trigger second factor authentication or use the "attrib_toggle" instead. Default value of this attribute is true.
Options in module_webauthn.php
scope
: FIDO2 is phishing-resistent by binding generated credentials to a scope. Browsers will only invoke the registration/authentication if the scope matches the principal domain name the user is currently visiting. If not specified, the scope will be the hostname of the IdP as per its metadata. It is permissible to widen the scope up to the prinicpal domain though (e.g. authentication service is "saml.example.com" => scope can be extended to "example.com"; but not "examp1e.com". A registered FIDO2 token can then also be used on other servers in the same domain. If configuring this item, be sure that the authentication server name and the desired scope are a suffix match.
registration / use_inflow_registration
: Optional parameter which determines whether you will be able to register and manage tokens while authenticating or you want to use the standalone registration page for these purposes. If set to false => standalone registration page, if true => inflow registration. If this parameter is not explicitly set, the value is considered to be true.
registration / auth_source
: Optional parameter to define how the user authenticates to the dedicated registration page. Defaults to "default-sp"; ignored if inflow registration was configured.
registration / policy_2fa / minimum_certification_level
: Required parameter which specifies the required FIDO certification level for registration, allowed values:
CERTIFICATION_NOT_REQUIRED
- attestation is not checkedFIDO_CERTIFIED_L1
- FIDO L1 certifiedFIDO_CERTIFIED_L1plus
- FIDO L1+ certifiedFIDO_CERTIFIED_L2
- FIDO L2 certifiedFIDO_CERTIFIED_L3
- FIDO L3 certifiedFIDO_CERTIFIED_L3plus
- FIDO L3+ certified
registration / policy_2fa / aaguid_whitelist
: Optional list of AAGUIDs which are excluded from the minimum certification level check. Defaults to an empty list. Ignored when minimum_certification_level
is set to CERTIFICATION_NOT_REQUIRED
.
registration / policy_2fa / attestation_format_whitelist
: Optional list of attestation formats which are excluded from the minimum certification level check. Defaults to an empty list. Ignored when minimum_certification_level
is set to CERTIFICATION_NOT_REQUIRED
.
registration / policy_passwordless / minimum_certification_level
: Required parameter, same meaning as registration / policy_2fa / minimum_certification_level
but for passwordless authentication
registration / policy_passwordless / aaguid_whitelist
: Optional parameter, same meaning as registration / policy_2fa / aaguid_whitelist
but for passwordless authentication
registration / policy_passwordless / attestation_format_whitelist
: Optional parameter, same meaning as registration / policy_2fa / attestation_format_whitelist
but for passwordless authentication
User Experience / Workflow
Users for which WebAuthn is enabled cannot continue without a FIDO2 token. The UI is different depending on the number of tokens the user has registered:
- User has 0 tokens: UI requires the user to register a token. The user can choose a convenient name for the token to recognise it later. If request_tokenmodel is set, the name will be appended with the token model and vendor. After successful registration, the authprocfilter is done (user continues to SP)
- User has 1 token: UI requires the user to authenticate. After the authentication, user can optionally enroll another token.
- User has 2+ tokens: UI requires the user to authenticate. After the authentication, user can optionally enroll another token or delete an obsolete one.
If a user is enabled but has forgotten all of his tokens, the person would need to contact his administrator and have his account temporarily disabled for two- factor authentication.
As long as a user account has 0 tokens there is no benefit yet; it's effectively still single factor authentication because anyone with the user's password can register any token. That is in the nature of things. It could be avoided with an out-of-band registration process (in the same scope).
If the standalone registration page is used, the user can't optionally enroll
and manage tokens while logging in.
The standalone registration page can be found under <basedir>module.php/webauthn/registration
,
it requires authentication (with the auth source registration_auth_source) and
after that you are redirected to a page where you can manage tokens.
Device model detection
The option registration / minimum_certification_level
can be used to get a
token's so-called AAGUID which uniquely identifies the model and manufacturer
(it is not a serial number). You can then make decisions about the acceptability
of a certain authenticator model.
Mapping the AAGUID to a cleartext model and manufacturer name is done by having (or not) meta-information about the AAGUID. The FIDO Alliance operates a Metadata Service (MDS) which has a good number of AAGUIDs registered. However, manufacturers are not required to submit their AAGUIDs and metadata to that MDS, and indeed, some manufacturers are missing.
The module contains a full list of AAGUIDs and relevant metadata as pulled from
the FIDO MDS. This list is in the config/webauthn-aaguid.json
file, and this
file needs to be moved to your SimpleSAMLphp configuration directory.
If you want, you can also manually update this file, if you believe there might
be new models listed. In order to do that, run the bin/updateMetadata.php
script like this:
where <blob file>
is the metadata JWT blob you get from
here.
As a consequence, depending on the token model the user uses, even if the AAGUID is being sent as part of the registration process, it may be that the device is still stored as unknown model/unknown vendor.
I contacted FIDO Alliance to ask about the lack of complete information in their MDS. Purportedly, listing in the MDS has chances of becoming mandatory in a future FIDO Certification. Until then, there is no good solution to the problem.
Disabling WebAuthn
You can disable the module entirely by not listing it as an authprocfilter.
You can disable the module by default by setting default_enable = false. You can
then enable WebAuthn second-factor authentication for individual users by adding
them with status "FIDO2Enabled" to the userstatus
table or if you don't want to
use the userstatus
table, you can send an attribute whose name is stored in
attrib_toggle
for this.
If the module is enabled by default, you can selectively disable WebAuthn
second-factor authentication by adding the username with status FIDO2Disabled to
the userstatus
table or if you don't want to use the userstatus
table, you
can send an attribute whose name is stored in attrib_toggle
for this.
Limitations / Design Decisions
This implementation does not validate token bindings, if sent by the authenticator (§7.1 Step 7 / §7.2 Step 11 skip token binding information validation if present). That is because Yubikeys do not support token binding and the corresponding functionality thus has no test case.
Both User Present and User Verified variants are considered sufficient to authenticate successfully in second-factor scenarios (§7.1 steps 11 and 12 are joined into one condition). The module logs into the credential database which of the two was used during registration time and does not allow downgrades during authentication time. Passwordless authentication always requires User Verified during registration and authentication transactions.
The implementation requests and supports ECDSA and RSA keys (algorithms -7, -257).
The implementation does not request any client extensions. The specification gives implementations a policy choice on what to do if a client sends extensions anyway: this implementation chose to then fail the registration/authentication.
The implementation supports the attestation formats
- "none" (No Attestation)
- "packed / x5c" (Packed Attestation, X.509 certificate)
- "packed / self" (Packed Attestation, Self-Attestation)
- "fido-u2f" (FIDO U2F Attestation)
- "apple" (Apple Anonymous Attestation)
- "android-key" (Android key attestation with Keymaster 4, for Android 9 and up) Other attestation formats lead to a registration failure.
For the attation type "packed / x5c",
- the optional OCSP checks are not performed (this is explicitly permitted in the spec due to other means of revocation checking in the FIDO MDS).
For both "packed / x5c" and "fido-u2f":
- all attestations are classified as "Basic" (i.e. no "AttCA" level); i.e. validation as per §7.1 Step 18 is not executed.
- Regarding §7.1 Step 21: When minimum certification levels are configured, "Self" and "Basic" attestation levels are considered acceptable; "None" is not acceptable.
If the implementation detects signs of physical object cloning (not incremented signature counter), it follows the policy of failing authentication.
All versions of simplesamlphp-module-webauthn with dependencies
ext-date Version *
ext-hash Version *
ext-openssl Version *
ext-pdo Version *
simplesamlphp/assert Version ^0.8.0
simplesamlphp/simplesamlphp Version ^2.0.0
spomky-labs/cbor-php Version ^2.1 || ^3.0
symfony/http-foundation Version ^5.4 || ^6.0
web-auth/cose-lib Version ^3.3 || ^4.0