Register Authenticators
During this step, your application will send a challenge to the device. The device will resolve this challenge by adding information and digitally signing the data.
The application will check the response from the device and get its credential ID. This ID will be used for further authentication requests.

Creation Request

To associate a device to a user, you need to instantiate a Webauthn\PublicKeyCredentialCreationOptions object.
It will need:
Let’s see an example of the PublicKeyCredentialCreationOptions object. The following example is a possible Public Key Creation page for a dummy user "@cypher-Angel-3000".
1
<?php
2
3
declare(strict_types=1);
4
5
use Cose\Algorithms;
6
use Webauthn\AuthenticatorSelectionCriteria;
7
use Webauthn\PublicKeyCredentialDescriptor;
8
use Webauthn\PublicKeyCredentialCreationOptions;
9
use Webauthn\PublicKeyCredentialParameters;
10
use Webauthn\PublicKeyCredentialRpEntity;
11
use Webauthn\PublicKeyCredentialUserEntity;
12
13
// RP Entity
14
$rpEntity = new PublicKeyCredentialRpEntity(
15
'My Super Secured Application', //Name
16
'foo.example.com', //ID
17
null //Icon
18
);
19
20
// User Entity
21
$userEntity = new PublicKeyCredentialUserEntity(
22
'@cypher-Angel-3000', //Name
23
'123e4567-e89b-12d3-a456-426655440000', //ID
24
'Mighty Mike', //Display name
25
null //Icon
26
);
27
28
// Challenge
29
$challenge = random_bytes(16);
30
31
// Timeout
32
$timeout = 60000; // 60 seconds
33
34
// Public Key Credential Parameters
35
$publicKeyCredentialParametersList = [
36
new PublicKeyCredentialParameters('public-key', Algorithms::COSE_ALGORITHM_ES256),
37
new PublicKeyCredentialParameters('public-key', Algorithms::COSE_ALGORITHM_RS256),
38
];
39
40
// Devices to exclude
41
$excludedPublicKeyDescriptors = [
42
new PublicKeyCredentialDescriptor(PublicKeyCredentialDescriptor::CREDENTIAL_TYPE_PUBLIC_KEY, 'ABCDEFGH…'),
43
];
44
45
$publicKeyCredentialCreationOptions = new PublicKeyCredentialCreationOptions(
46
$rpEntity,
47
$userEntity,
48
$challenge,
49
$publicKeyCredentialParametersList,
50
$timeout,
51
$excludedPublicKeyDescriptors,
52
new AuthenticatorSelectionCriteria(),
53
PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE,
54
null // Extensions
55
);
Copied!
The options object can be converted into JSON and sent to the authenticator using a JS script.
It is important to store the user entity and the options object (e.g. in the session) for the next step; they will be needed to check the response from the device.

Creation Response

What you receive must be a JSON object that looks like as follow:
1
{
2
"id":"KVb8CnwDjpgAo[…]op61BTLaa0tczXvz4JrQ23usxVHA8QJZi3L9GZLsAtkcVvWObA",
3
"type":"public-key",
4
"rawId":"KVb8CnwDjpgAo[…]rQ23usxVHA8QJZi3L9GZLsAtkcVvWObA==",
5
"response":{
6
"clientDataJSON":"eyJjaGFsbGVuZ2UiOiJQbk1hVjBVTS[…]1iUkdHLUc4Y3BDSdGUifQ==",
7
"attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSj[…]YcGhf"
8
}
9
}
Copied!
There are two steps to perform with this object:
    Load the data
    Verify it with the creation options set above

Data Loading

Now that all components are set, we can load the data we receive using the Public Key Credential Loader service (variable $publicKeyCredential).
1
<?php
2
3
declare(strict_types=1);
4
5
$data = '
6
{
7
"id":"KVb8CnwDjpgAo[…]op61BTLaa0tczXvz4JrQ23usxVHA8QJZi3L9GZLsAtkcVvWObA",
8
"type":"public-key",
9
"rawId":"KVb8CnwDjpgAo[…]rQ23usxVHA8QJZi3L9GZLsAtkcVvWObA==",
10
"response":{
11
"clientDataJSON":"eyJjaGFsbGVuZ2UiOiJQbk1hVjBVTS[…]1iUkdHLUc4Y3BDSdGUifQ==",
12
"attestationObject":"o2NmbXRmcGFja2VkZ2F0dFN0bXSj[…]YcGhf"
13
}
14
}';
15
16
$publicKeyCredential = $publicKeyCredentialLoader->load($data);
Copied!
If no exception is thrown, you can go to the next step: the verification.

Response Verification

Now we have a fully loaded Public Key Credential object, but we need now to make sure that:
    1.
    The authenticator response is of type AuthenticatorAttestationResponse
    2.
    This response is valid.
The first is easy to perform:
1
<?php
2
3
declare(strict_types=1);
4
5
use Webauthn\AuthenticatorAttestationResponse;
6
7
$authenticatorAttestationResponse = $publicKeyCredential->getResponse();
8
if (!$authenticatorAttestationResponse instanceof AuthenticatorAttestationResponse) {
9
//e.g. process here with a redirection to the public key creation page.
10
}
Copied!
The second step is the verification against
    The Public Key Creation Options we created earlier,
    The HTTP request
The Authenticator Attestation Response Validator service (variable $authenticatorAttestationResponseValidator) will check everything for you: challenge, origin, attestation statement and much more.
The library needs PSR-7 requests. In the example below, we use nyholm/psr7-server to get that request.
1
<?php
2
3
declare(strict_types=1);
4
5
use Nyholm\Psr7\Factory\Psr17Factory;
6
use Nyholm\Psr7Server\ServerRequestCreator;
7
8
$psr17Factory = new Psr17Factory();
9
$creator = new ServerRequestCreator(
10
$psr17Factory, // ServerRequestFactory
11
$psr17Factory, // UriFactory
12
$psr17Factory, // UploadedFileFactory
13
$psr17Factory // StreamFactory
14
);
15
16
$serverRequest = $creator->fromGlobals();
17
18
$publicKeyCredentialSource = $authenticatorAttestationResponseValidator->check(
19
$authenticatorAttestationResponse,
20
$publicKeyCredentialCreationOptions,
21
$serverRequest
22
);
Copied!
If no exception is thrown, the response is valid. You can store the Public Key Credential Source ($publicKeyCredentialSource) and associate it to the user entity.
The way you store and associate these objects to the user is out of scope of this library. However, please note that these objects implement \JsonSerializable and have a static method createFromJson(string $json). This will allow you to serialize the objects into JSON and easily go back to an object.
If you have just registered a new user, don’t forget to store it in your database as well.
Last modified 1d ago