Register Additional Authenticators

Search…
In some circumstances, you may need to register a new authenticator for a user e.g. when adding a new authenticator or when an administrator acts as another user to replace a lost device.
It is possible to perform this ceremony programmatically.
You can attach several authenticators to a user account. It is recommended in case of lost devices or if the user gets access on your application using multiple platforms (smartphone, laptop…).
With a Symfony application, the fastest way for a user to register additional authenticators is to use the “controller” feature.
To add a new authenticator to a user, the bundle needs to know to whom it should be added. This can be:
The current user itself e.g. from its own account
An administrator acting for another user from a dashboard
For that purpose, a User Entity Guesser service should be created. This service shall implement the interface Webauthn\Bundle\Security\Guesser\UserEntityGuesser and its unique method findUserEntity.
You can directly use the Webauthn\Bundle\Security\Guesser\CurrentUserEntityGuesser as a Symfony service. It is designed to identify the user that is currently logged in.
In the example herafter where the current user is guessed using a controller parameter. This can be used when an administrator is adding an authenticator to another user account.
App\Guesser\FromQueryParameterGuesser.php
1
<?php
2
​
3
declare(strict_types=1);
4
​
5
namespace App\Guesser;
6
​
7
use Assert\Assertion;
8
use Symfony\Component\HttpFoundation\Request;
9
use Webauthn\Bundle\Repository\PublicKeyCredentialUserEntityRepository;
10
use Webauthn\Bundle\Security\Guesser\UserEntityGuesser;
11
use Webauthn\PublicKeyCredentialUserEntity;
12
​
13
final class FromQueryParameterGuesser implements UserEntityGuesser
14
{
15
    public function __construct(
16
        private PublicKeyCredentialUserEntityRepository $userEntityRepository
17
    ) {
18
    }
19
​
20
    public function findUserEntity(Request $request): PublicKeyCredentialUserEntity
21
    {
22
        $userHandle = $request->query->get('user_id');
23
        Assertion::string($userHandle, 'User entity not found. Invalid user ID');
24
        $user = $this->userEntityRepository->findOneByUserHandle($userHandle);
25
        Assertion::isInstanceOf($user, PublicKeyCredentialUserEntity::class, 'User entity not found.');
26
​
27
        return $user;
28
    }
29
}
Copied!
In the case the current user s supposed to be administrator, the user entity can be determined using the query parameters and a route like /admin/add-authenticator/for/{user_id}.
Now you just have to enable the feature and set the routes to your options and response controllers.
1
webauthn:
2
    controllers:
3
        enabled: true # We enable the feature
4
        creation:
5
            from_user_account: # Endpoints accessible by the user itself
6
                options_path: '/profile/security/devices/add/options' # Path to the creation options controller
7
                result_path: '/profile/security/devices/add' # Path to the response controller
8
                user_entity_guesser: Webauthn\Bundle\Security\Guesser\CurrentUserEntityGuesser # See above
9
            from_admin_dashboard: # Endpoint accessible by an administrator
10
                options_path: '/admin/security/user/{user_id}/devices/add/options' # Path to the creation options controller
11
                result_path: '/admin/security/user/{user_id}/devices/add' # Path to the response controller
12
                user_entity_guesser: App\Guesser\FromQueryParameterGuesser # From the example
Copied!
As the user shall be authenticated to register a new authenticator, you should protect these routes in the security.yaml file.
config/packages/security.yaml
1
security:
2
    access_control:
3
        - { path: ^/profile,  roles: IS_AUTHENTICATED_FULLY } # We protect all the /profile path
4
        - { path: ^/admin,  roles: ROLE_ADMIN }
Copied!
Now you can send requests to these new endpoints. For example, if you are using the Javascript library, the calls will look like as follow:
1
// Import the registration hook
2
import {useRegistration} from 'webauthn-helper';
3
​
4
// Create your register function.
5
// By default the urls are "/register" and "/register/options"
6
// but you can change those urls if needed.
7
const register = useRegistration({
8
    actionUrl: '/profile/security/devices/add',
9
    optionsUrl: '/profile/security/devices/add/options'
10
});
11
​
12
​
13
// We can call this register function whenever we need
14
//   No "username" or "displayName" parameters are needed
15
//   as the user entity is guessed by the dedicated service
16
register({})
17
    .then((response) => console.log('Registration success'))
18
    .catch((error) => console.log('Registration failure'))
19
;
Copied!
Creation Profile
The default creation profile is used. You can change it using the dedicated option.
1
webauthn:
2
    controllers:
3
        enabled: true
4
        creation:
5
            from_user_account:
6
                …
7
                profile: custom_profile
Copied!
Response Handlers
You can customize the responses returned by the controllers by using custom handlers. This could be useful when you want to return additional information to your application.
There are 3 types of responses and handlers:
Creation options,
Success,
Failure.
Creation Options Handler
This handler is called during the registration of a authenticator and has to implement the interface Webauthn\Bundle\Security\Handler\CreationOptionsHandler.
1
webauthn:
2
    controllers:
3
        enabled: true
4
        creation:
5
            from_user_account:
6
                …
7
                options_handler: … # Your handler here
Copied!
Success Handler
This handler is called when a client sends a valid assertion from the authenticator. This handler shall implement the interface Webauthn\Bundle\Security\Handler\SuccessHandler. The default handler is Webauthn\Bundle\Service\DefaultSuccessHandler.
1
webauthn:
2
    controllers:
3
        enabled: true
4
        creation:
5
            from_user_account:
6
                …
7
                success_handler: … # Your handler here
Copied!
Failure Handler
This handler is called when an error occurred during the process. This handler shall implement the interface Webauthn\Bundle\Security\Handler\SuccessHandler. The default handler is Webauthn\Bundle\Service\DefaultFailureHandler.
1
webauthn:
2
    controllers:
3
        enabled: true
4
        creation:
5
            from_user_account:
6
                …
7
                failure_handler: … # Your handler here
Copied!
Symfony Bundle - Previous
Advanced Behaviors
Debugging
Last modified 2mo ago
Export as PDF
Copy link
Edit on GitHub
Contents
Creation Profile
Response Handlers