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.
Assertion Request
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)
Allowed Credentials
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.
// We gather all registered authenticators for this user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
// We don’t need the Credential Sources, just the associated Descriptors
$allowedCredentials = array_map(
static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
return $credential->getPublicKeyCredentialDescriptor();
},
$registeredAuthenticators
);
Example
<?php
declare(strict_types=1);
use Webauthn\PublicKeyCredentialDescriptor;
use Webauthn\PublicKeyCredentialRequestOptions;
use Webauthn\PublicKeyCredentialSource;
// List of registered PublicKeyCredentialDescriptor classes associated to the user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
$allowedCredentials = array_map(
static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
return $credential->getPublicKeyCredentialDescriptor();
},
$registeredAuthenticators
);
// Public Key Credential Request Options
$publicKeyCredentialRequestOptions =
PublicKeyCredentialRequestOptions::create(
random_bytes(32) // Challenge
)
->allowCredentials(...$allowedCredentials)
;
User Verification
<?php
declare(strict_types=1);
use Webauthn\PublicKeyCredentialDescriptor;
use Webauthn\PublicKeyCredentialRequestOptions;
use Webauthn\PublicKeyCredentialSource;
// List of registered PublicKeyCredentialDescriptor classes associated to the user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
$allowedCredentials = array_map(
static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
return $credential->getPublicKeyCredentialDescriptor();
},
$registeredAuthenticators
);
// Public Key Credential Request Options
$publicKeyCredentialRequestOptions =
PublicKeyCredentialRequestOptions::create(
random_bytes(32) // Challenge
)
->setUserVerification(
PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_REQUIRED
)
;
Extensions
<?php
declare(strict_types=1);
use Webauthn\PublicKeyCredentialRequestOptions;
// List of registered PublicKeyCredentialDescriptor classes associated to the user
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
$allowedCredentials = array_map(
static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
return $credential->getPublicKeyCredentialDescriptor();
},
$registeredAuthenticators
);
// Public Key Credential Request Options
$publicKeyCredentialRequestOptions =
PublicKeyCredentialRequestOptions::create(
random_bytes(32) // Challenge
)
->addExtension(
AuthenticationExtension::create('loc', true),
AuthenticationExtension::create('txAuthSimple', 'Please log in with a registered authenticator'),
)
;
Response Handling
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:
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:
<?php
declare(strict_types=1);
use Webauthn\AuthenticatorAssertionResponse;
$authenticatorAssertionResponse = $publicKeyCredential->getResponse();
if (!$authenticatorAssertionResponse instanceof AuthenticatorAssertionResponse) {
//e.g. process here with a redirection to the public key login/MFA page.
}
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.
For usernameless authentication, please read the . 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 for all possible values.
Please refer to the to know how to manage authentication extensions.
This step is exactly the same as the one described in process.
