Extensions
The mechanism for generating public key credentials, as well as requesting and generating Authentication assertions, can be extended to suit particular use cases. Each case is addressed by defining a registration extension.
This library is ready to handle extension inputs and outputs, but no concrete implementations are provided.
It is up to you, depending on the extensions you want to support, to create the extension handlers.

Creation/Request Options

The following example is totally fictive. We will add an extension input loc=true to the request option object.
1
<?php
2
3
declare(strict_types=1);
4
5
use Webauthn\AuthenticationExtensions\AuthenticationExtension;
6
use Webauthn\AuthenticationExtensions\AuthenticationExtensionsClientInputs;
7
use Webauthn\PublicKeyCredentialRequestOptions;
8
9
// Extensions
10
$extensions = new AuthenticationExtensionsClientInputs();
11
$extensions->add(new AuthenticationExtension('loc', true));
12
13
// List of registered PublicKeyCredentialDescriptor classes associated to the user
14
$registeredPublicKeyCredentialDescriptors =;
15
16
// Public Key Credential Request Options
17
$publicKeyCredentialRequestOptions = new PublicKeyCredentialRequestOptions(
18
random_bytes(32), // Challenge
19
60000, // Timeout
20
'foo.example.com', // Relying Party ID
21
$registeredPublicKeyCredentialDescriptors, // Registered PublicKeyCredentialDescriptor classes
22
PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_PREFERRED, // User verification requirement
23
$extensions
24
);
Copied!

Extension Output Checker

An Extension Output Checker will check the extension inputs and output.
It must implement the interface Webauthn\AuthenticationExtensions\ExtensionOutputChecker and throw an exception of type Webauthn\AuthenticationExtension\ExtensionOutputError in case of error.
Devices may ignore the extension inputs. The extension outputs are therefore not guaranteed.
In the previous example, we asked for the location of the device and we expect to receive geolocation data in the extension output.
1
<?php
2
3
declare(strict_types=1);
4
5
namespace Acme\Extension;
6
7
use Webauthn\AuthenticationExtensions\ExtensionOutputChecker;
8
use Webauthn\AuthenticationExtensions\ExtensionOutputError;
9
10
final class LocationExtensionOutputChecker
11
{
12
public function check(AuthenticationExtensionsClientInputs $inputs, AuthenticationExtensionsClientOutputs $outputs): void
13
{
14
if (!$inputs->has('loc') || $inputs->get('loc') !== true) {
15
return;
16
}
17
18
if (!$outputs->has('loc')) {
19
//You may simply return but here we consider it is a mandatory extension output.
20
throw new ExtensionOutputError(
21
$inputs->get('loc'),
22
'The location of the device is missing'
23
);
24
}
25
26
$location = $outputs->get('loc');
27
//... Proceed with the output e.g. by logging the location of the device
28
// or verifying it is in a specific area.
29
}
30
}
Copied!

Extension Input

To enable an authenticator feature like the geolocation, you must ask it through the creation or the request option objects.

The Easy Way

Authenticator registration

1
<?php
2
3
declare(strict_types=1);
4
5
use Webauthn\AuthenticationExtensions\AuthenticationExtension;
6
use Webauthn\AuthenticationExtensions\AuthenticationExtensionsClientInputs;
7
8
// Extensions
9
$extensions = new AuthenticationExtensionsClientInputs();
10
$extensions->add(new AuthenticationExtension('loc', true));
11
12
$publicKeyCredentialCreationOptions = $server->generatePublicKeyCredentialCreationOptions(
13
$userEntity,
14
$attestationMode,
15
$excludedPublicKeyDescriptors, $authenticatorSelectionCriteria,
16
$extensions
17
);
Copied!

User Authentication

1
<?php
2
3
use Webauthn\AuthenticationExtensions\AuthenticationExtension;
4
use Webauthn\AuthenticationExtensions\AuthenticationExtensionsClientInputs;
5
use Webauthn\PublicKeyCredentialCreationOptions;
6
7
// Extensions
8
$extensions = new AuthenticationExtensionsClientInputs();
9
$extensions->add(new AuthenticationExtension('loc', true));
10
11
$publicKeyCredentialRequestOptions = $server->generatePublicKeyCredentialRequestOptions(
12
PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_PREFERRED,
13
$allowedCredentials
14
$extensions
15
);
Copied!

The Hard Way

Authenticator registration

1
<?php
2
3
declare(strict_types=1);
4
5
use Webauthn\AuthenticationExtensions\AuthenticationExtension;
6
use Webauthn\AuthenticationExtensions\AuthenticationExtensionsClientInputs;
7
use Webauthn\PublicKeyCredentialCreationOptions;
8
9
// Extensions
10
$extensions = new AuthenticationExtensionsClientInputs();
11
$extensions->add(new AuthenticationExtension('loc', true));
12
13
$publicKeyCredentialCreationOptions = new PublicKeyCredentialCreationOptions(
14
$rpEntity,
15
$userEntity,
16
$challenge,
17
$publicKeyCredentialParametersList,
18
$timeout,
19
$excludedPublicKeyDescriptors,
20
$authenticatorSelectionCriteria,
21
PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE,
22
$extensions
23
);
Copied!

User Authentication

1
<?php
2
3
declare(strict_types=1);
4
5
use Webauthn\AuthenticationExtensions\AuthenticationExtension;
6
use Webauthn\AuthenticationExtensions\AuthenticationExtensionsClientInputs;
7
use Webauthn\PublicKeyCredentialRequestOptions;
8
9
// Extensions
10
$extensions = new AuthenticationExtensionsClientInputs();
11
$extensions->add(new AuthenticationExtension('loc', true));
12
13
// List of registered PublicKeyCredentialDescriptor classes associated to the user
14
$registeredAuthenticators = $publicKeyCredentialSourceRepository->findAllForUserEntity($userEntity);
15
$allowedCredentials = array_map(
16
static function (PublicKeyCredentialSource $credential): PublicKeyCredentialDescriptor {
17
return $credential->getPublicKeyCredentialDescriptor();
18
},
19
$registeredAuthenticators
20
);
21
22
// Public Key Credential Request Options
23
$publicKeyCredentialRequestOptions = new PublicKeyCredentialRequestOptions(
24
random_bytes(32), // Challenge
25
60000, // Timeout
26
'foo.example.com', // Relying Party ID
27
$allowedCredentials, // Registered PublicKeyCredentialDescriptor classes
28
PublicKeyCredentialRequestOptions::USER_VERIFICATION_REQUIREMENT_PREFERRED, // User verification requirement
29
$extensions // Extensions
30
);
Copied!

The Symfony Way

The easiest way to manage that is by using the creation and request profiles.
config/packages/webauthn.yaml
1
webauthn:
2
3
creation_profiles:
4
default:
5
rp:
6
name: 'My Application'
7
id: 'example.com'
8
extensions:
9
loc: true
10
request_profiles:
11
default:
12
rp_id: 'example.com'
13
extensions:
14
loc: true
Copied!
Last modified 1mo ago