1 of 3

The Symfony Way

Lucky Symfony applications!

An official bundle is provided in the package web-auth/webauthn-symfony-bundle.

Starting at v3.2.4, the bundle can be installed on Symfony 4.4 or 5.0+.

If you use Laravel, you may be interested in this project: https://github.com/asbiin/laravel-webauthn

Before installing it, please make sure you installed and configured:

The package symfony/psr-http-message-bridge ,
The package nyholm/psr7 or any other PSR-7 package,
The SensioFrameworkExtraBundle and enabled the PSR-7 support.

composer require symfony/psr-http-message-bridge nyholm/psr7 annotations

config/packages/sensio:framework:extra.yaml

sensio_framework_extra:
    psr_message:
        enabled: true

If you are using Symfony Flex then the bundle will automatically be installed and the default configuration will be set. Otherwise you need to add it in your AppKernel.php file:

src/AppKernel.php

<?php

public function registerBundles()
{
    $bundles = [
        // ...
        new Webauthn\Bundle\WebauthnBundle(),
    ];
}

And add the Webauthn Route Loader:

config/routes/webauthn:routes.php

<?php

declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes) {
    $routes->import('.', 'webauthn');
};

Repositories

The first step is to create your credential and user entity repositories.

Only Doctrine ORM based repositories are provided. Other storage systems like filesystem or Doctrine ODM may be added in the future but, at the moment, you have to create these from scratch.

Configuration

With Flex, you have a minimal configuration file installed through a Flex Recipe. You must set the repositories you have just created. You also have to modify the environment variables Relying_PARTY_ID and Relying_PARTY_NAME.

You may also need to adjust other parameters.

If you don’t use Flex, hereafter an example of configuration file:

config/packages/webauthn.yaml

webauthn:
#    logger: null # PSR-3 compatible logging service
    credential_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialSourceRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
    user_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialUserEntityRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
    token_binding_support_handler: 'Webauthn\TokenBinding\IgnoreTokenBindingHandler' # We ignore the token binding instructions by default
    creation_profiles: # Authenticator registration profiles
        default: # Unique name of the profile
            rp: # Relying Party information
                name: '%env(Relying_PARTY_NAME)%' # CHANGE THIS! or create the corresponding env variable
                id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
#                icon: null # Secured image (data:// scheme)
#            challenge_length: 32
#            timeout: 60000
#            authenticator_selection_criteria:
#                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE
#                require_resident_key: false
#                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
#            extensions:
#                loc: true
#            public_key_credential_parameters: # You should not change this list
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_EdDSA #Order is important. Preferred algorithms go first
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256K
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES512
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS512
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS512
#            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE
    request_profiles: # Authentication profiles
        default: # Unique name of the profile
            rp_id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
#            challenge_length: 32
#            timeout: 60000
#            user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
#            extensions:
#                loc: true
#    metadata_service:
#        enabled: false
#        repository: 'App\Repository\MetadataStatementRepository'

Repositories

The credential_repository and user_repository parameters correspond to the services we created above.

Token Binding Handler

Please refer to this page. You should let the default value as it is.

Creation Profiles

If you don't create the creation_profiles section, a default profile is set.

Relying Party (rp)

The realying Party corresponds to your application. Please refer to this page for more information.

The parameter id is optional but highly recommended.

Challenge Length

By default, the length of the challenge is 32 bytes. You may need to select a smaller or higher length. This length can be configured for each profile:

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            challenge_length: 16

Timeout

The default timeout is set to 60 seconds (60 000 milliseconds). You can change this value as follows:

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            timeout: 30000

For v4.0+, the timeout will be set to null. The values recommended by the specification are as follow:

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)

Authenticator Selection Criteria

This set of options allows you to select authenticators depending on their capabilities. The values are described in the advanced concepts of the protocol.

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            authenticator_selection_criteria:
                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM
                require_resident_key: true
                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED

Public Key Credential Parameters

This option indicates the algorithms allowed for your application. By default, a large list of algorithms is defined, but you can add custom algorithms or reduce the list.

The order is important. Preferred algorithms go first.

It is not recommended changing the default list unless you exactly know what you are doing.

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            public_key_credential_parameters:
                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256

Attestation Conveyance

If you need the attestation of the authenticator, you can specify the preference regarding attestation conveyance during credential generation.

Please note that the metadata service is mandatory when you use this option.

The use of Attestation Statements is generally not recommended unless you REALLY need this information.

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT

Extensions

You can set as many extensions as you want in the profile. Please also refer to this page for more information.

The example below is totally fictive. Some extensions are defined in the specification but the support depends on the authenticators, on the browsers and on the relying parties (your applications).

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            extensions:
                loc: true
                txAuthSimple: 'Please add your new authenticator'

Request Profiles

If you don't create the creation_profiles section, a default profile is set.

The parameters for the request profiles (i.e. the authentication) are very similar to the creation profiles. The only difference is that you don’t need all the detail of the Relying Party, but only its ID (i.e. its domain).

app/config/webauthn.yaml

webauthn:
    request_profiles:
        acme:
            rp_id: 'example.com'

Please note that all parameters are optional. The following configuration is perfectly valid. However, and as mentioned above, the parameter id is highly recommended.

app/config/webauthn.yaml

webauthn:
    request_profiles:
        acme: ~

Firewall

Now you have a fully configured bundle, you can protect your routes and manage the user registration and authenticatin through the Symfony Firewall.

Entities with Doctrine

Credential Source

The Doctrine Entity

With Doctrine, you have to indicate how to store the Credential Source objects. Hereafter an example of an entity. In this example we add an entity id and a custom field created_at. We also indicate the repository as we will have a custom one.

As the ID must have a fixed length and because the credentialId field of Webauthn\PublicKeyCredentialSource hasn’t such a requirement and is a binary string, thus we need to declare our own id field.

Do not forget to update your database schema!

The Repository

To ease the integration into your application, the bundle provides a concrete class that you can extend.

In this following example, we extend that class and add a method to get all credentials for a specific user handle. Feel free to add your own methods.

We must override the method saveCredentialSource because we may receive Webauthn\PublicKeyCredentialSource objects instead of App\Entity\PublicKeyCredentialSource.

This repository should be declared as a Symfony service.

With Symfony Flex, this is usually done automatically

User Entity

Doctrine Entity

In a Symfony application context, you usually have to manage several user entities. Thus, in the following example, the user entity class will extend the required calls and implement the interface provided by the Symfony Security component.

Feel free to add the necessary setters as well as other fields you need (creation date, last update at…).

Please note that the ID of the user IS NOT generated by Doctrine and must be a string. We highly recommend you to use UUIDs.

The Repository

The following example uses Doctrine to create, persist or perform queries using the User objects created above.

This repository should be declared as a Symfony service.

With Symfony 4, this is usually done automatically

Firewall

How to register and authenticate my users?

Security Bundle

To authenticate or register your users with Symfony, the best and easiest way is to use the Security Bundle. First, install that bundle.

composer require symfony/security-bundle

Next, you have to create a custom user provider that will retrieve users on login requests. The following example uses the user repository showed on this page.

src/Repository/UserRepository.php

<?php

namespace App\Security;

use App\Entity\User;
use App\Repository\UserRepository;
use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;

class UserProvider implements UserProviderInterface
{
    /**
     * @var UserRepository
     */
    private $userRepository;

    public function __construct(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    /**
     * @throws UsernameNotFoundException if the user is not found
     */
    public function loadUserByUsername($username): UserInterface
    {
        $user = $this->userRepository->find($username);
        if (null !== $user) {
            return $user;
        }

        throw new UsernameNotFoundException(sprintf('User with name "%s" does not exist', $username));
    }

    public function refreshUser(UserInterface $user): UserInterface
    {
        if (!$user instanceof User) {
            throw new UnsupportedUserException(sprintf('Invalid user class "%s".', get_class($user)));
        }

        return $this->loadUserByUsername($user->getUsername());
    }

    public function supportsClass($class): bool
    {
        return User::class === $class;
    }
}

Firewall Configuration

Now you can tell Symfony to use your user provider and you enable the dedicated firewall

config/packages/security.yaml

security:
    providers:
        main:
            id: 'App\Security\UserProvider'
    firewalls:
        main:
            webauthn: ~

In some case, you may have several user providers that are used by other parts of your application. This Webauthn bundle allow you to override the default user provider.

config/packages/security.yaml

security:
    providers:
        backend_users:
            memory:
                users:
                    john_admin: { password: '$2y$13$jxGxc ... IuqDju', roles: ['ROLE_ADMIN'] }
                    jane_admin: { password: '$2y$13$PFi1I ... rGwXCZ', roles: ['ROLE_ADMIN', 'ROLE_SUPER_ADMIN'] }
    firewalls:
        backend:
            pattern: ^/backend/
            # ... Add your configuration here
            
        main:
            webauthn:
                user_provider: 'App\Security\UserProvider'

Logout

Users can logout as usual. You just have to add the logout configuration under your firewall and add the route.

config/packages/security.yaml

security:
    # ...

    firewalls:
        main:
            # ...
            logout: ~

User Authentication

As you have noticed, there is nothing to configure to have a fully functional firewall. The firewall routes are automatically created for you. They are namely:

/login/options: to create the request options (POST only)
/login: to submit the assertion response (POST only)

You should also ensure to allow anonymous users to contact those endpoints.

security:
    access_control:
        - { path: ^/login,  roles: IS_AUTHENTICATED_ANONYMOUSLY }

Credential Request Options

Prior to the authentication of the user, you must create a PublicKey Credential Request Options object. To do so, send a POST request to /login/options.

The body of this request is a JSON object that must contain a username field with the name of the user being authenticated.

No need to reinvent the wheel, you can use the webauthn-helper package.

It is mandatory to set the Content-Type header to application/json.

fetch('/login/options', {
    method  : 'POST',
    credentials : 'same-origin',
    headers : {
        'Content-Type' : 'application/json'
    },
    body: JSON.stringify({
        "username": "johndoe@example.com"
    })
}).then(function (response) {
    return response.json();
}).then(function (json) {
    console.log(json);
}).catch(function (err) {
    console.log({ 'status': 'failed', 'error': err });
})

In case of success, you receive a valid PublicKeyCredentialRequestOptions object and your user will be asked to interact with one of its registered security devices.

The default path is /login/options. You can change it if needed:

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    routes:
                        options_path: /security/authentication/options
    access_control:
        - { path: ^/security/authentication/options,  roles: IS_AUTHENTICATED_ANONYMOUSLY}

Assertion Response

When the user touched the security device, you will receive a response from it. You just have to send a POST request to /login.

The body of this request is the response of the security device.

It is mandatory to set the Content-Type header to application/json.

fetch('/login', {
    method  : 'POST',
    credentials : 'same-origin',
    headers : {
        'Content-Type' : 'application/json'
    },
    body: //put the security device response here
}).then(function (response) {
    return response.json();
}).then(function (json) {
    console.log(json);
}).catch(function (err) {
    console.log({ 'status': 'failed', 'error': err });
})

The default path is /login. You can change that path if needed:

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    routes:
                        result_path: /security/authentication/login

Your user can now be authenticated and retrieved as usual.

Acme\Controller\AdminController.php

<?php

declare(strict_types=1);

namespace Acme\Controller;

use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;

final class AdminController
{
    /**
     * @var TokenStorageInterface
     */
    private $tokenStorage:

    public function __construct(TokenStorageInterface $tokenStorage)
    {
        $this->tokenStorage = $tokenStorage;
    }

    public function __invoke()
    {
        // $token is an object of type Webauthn\Bundle\Security\Authentication\Token\WebauthnToken
        $token = $this->tokenStorage->getToken();
        ...
    }
}

Request Profile

By default, the default profile is used. You may have created a request profile in the bundle configuration. You can use this profile instead of the default one.

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    profile: 'acme'

User Registration

The user registration is also managed by the firewall. It is disabled by default. If you want that feature, please enable it:

security:
    firewalls:
        main:
            webauthn:
                registration:
                    enabled: true

The firewall routes are automatically created for you. They are namely:

/register/options: to create the creation options (POST only)
/register: to submit the attestation response (POST only)

You should also ensure to allow anonymous users to contact those endpoints.

security:
    access_control:
        - { path: ^/register,  roles: IS_AUTHENTICATED_ANONYMOUSLY }

Credential Creation Options

Prior to the registration of a user and its authenticator, you must create a PublicKey Credential Creation Options object. To do so, send a POST request to /register/options.

The body of this request is a JSON object that must contain username and displayName fields with the username of the user being registered and the name displayed in the application.

It is mandatory to set the Content-Type header to application/json.

fetch('/register/options', {
        method  : 'POST',
        credentials : 'same-origin',
        headers : {
            'Content-Type' : 'application/json'
        },
        body: JSON.stringify({
            "username": "johndoe@example.com",
            "displayName": "John Doe"
        })
    }).then(function (response) {
        return response.json();
    }).then(function (json) {
        console.log(json);
    }).catch(function (err) {
        console.log({ 'status': 'failed', 'error': err });
    })

In case of success, you receive a valid PublicKeyCredentialCreationOptions object and your user will be asked to interact with its security device.

The default path is /register/options. You can change it if needed:

security:
    firewalls:
        main:
            webauthn:
                registration:
                    routes:
                        options_path: /security/registration/options
    access_control:
        - { path: ^/security/registration/options,  roles: IS_AUTHENTICATED_ANONYMOUSLY}

Attestation Response

When the user touched the security device, you will receive a response from it. You just have to send a POST request to /register.

The body of this request is the response of the security device.

It is mandatory to set the Content-Type header to application/json.

fetch('/register', {
    method  : 'POST',
    credentials : 'same-origin',
    headers : {
        'Content-Type' : 'application/json'
    },
    body: //put the security device response here
}).then(function (response) {
    return response.json();
}).then(function (json) {
    console.log(json);
}).catch(function (err) {
    console.log({ 'status': 'failed', 'error': err });
})

The default path is /register. You can change that path is needed:

security:
    firewalls:
        main:
            webauthn:
                registration:
                    routes:
                        result_path: /security/registration/result

In case of success, the user and the authenticator are correctly registered and automatically logged in.

Creation Profile

By default, the default profile is used. You may have created a creation profile in the bundle configuration. You can use this profile instead of the default one.

security:
    firewalls:
        main:
            webauthn:
                registration:
                    profile: 'acme'

Authentication Attributes

The security token returned by the firewall sets some attributes depending on the assertion and the capabilities of the authenticator. The attributes are:

IS_USER_PRESENT: the user was present during the authentication ceremony. This attribute is usually set to true by authenticators,
IS_USER_VERIFIED: the user was verified by the authenticator. Verification may be performed by several means including biometrics ones (fingerprint, iris, facial recognition…).

You can then set constraints to the access controls. In the example below, the /admin path can be reached by users with the role ROLE_ADMIN and that have been verified during the ceremony.

security:
    access_control:
        - { path: ^/admin,  roles: [ROLE_ADMIN, IS_USER_VERIFIED]}

Options Storage

Webauthn authentication and registration are 2 steps round trip processes:

Options issuance
Authenticator response verification

It is required to store the options and the user entity associated to it to verify the authenticator responses.

By default, the firewall uses Webauthn\Bundle\Security\Storage\SessionStorage. This storage system stores the data in a session.

If this behaviour does not fit on your needs (e.g. you want to use a database, Redis…), you can implement a custom data storage for that purpose. Your custom storage system has to implement Webauthn\Bundle\Security\Storage\RequestOptionsStorage and be declared as a container service.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                options_storage: 'App\Handler\MyCustomRequestOptionsStorage'

Response Handlers

You can customize the responses returned by the firewall by using a custom handler. This could be useful when you want to return additional information to your application.

There are 4 types of responses and handlers:

Request options,
Creation options,
Authentication Success,
Authentication Failure,

Request Options Handler

This handler is called when a client sends a valid POST request to the options_path during the authentication process. The default Request Options Handler is Webauthn\Bundle\Security\Handler\DefaultRequestOptionsHandler. It returns a JSON Response with the Public Key Credential Request Options objects in its body.

Your custom handler has to implement the interface Webauthn\Bundle\Security\Handler\RequestOptionsHandler and be declared as a service.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    options_handler: 'App\Handler\MyCustomRequestOptionsHandler'

Creation Options Handler

This handler is very similar to the previous one, except that it is called during the registration of a new user and has to implement the interface Webauthn\Bundle\Security\Handler\CreationOptionsHandler.

ecurity:
    firewalls:
        main:
            webauthn:
                registration:
                    options_handler: 'App\Handler\MyCustomRequestOptionsHandler'

Authentication Success Handler

This handler is called when a client sends a valid assertion from the authenticator. The default handler is Webauthn\Bundle\Security\Handler\DefaultSuccessHandler.

Your custom handler has to implement the interface Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface and be declared as a container service.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                success_handler: 'App\Handler\MyCustomAuthenticationSuccessHandler'

Authentication Failure Handler

This handler is called when an error occurred during the authentication process. The default handler is Webauthn\Bundle\Security\Handler\DefaultFailureHandler.

Your custom handler has to implement the interface Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface and be declared as a container service.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                failure_handler: 'App\Handler\MyCustomAuthenticationFailureHandler'

The Symfony Way

Lucky Symfony applications!

An official bundle is provided in the package web-auth/webauthn-symfony-bundle.

Starting at v3.2.4, the bundle can be installed on Symfony 4.4 or 5.0+.

If you use Laravel, you may be interested in this project: https://github.com/asbiin/laravel-webauthn

Before installing it, please make sure you installed and configured:

The package symfony/psr-http-message-bridge ,
The package nyholm/psr7 or any other PSR-7 package,
The SensioFrameworkExtraBundle and enabled the PSR-7 support.

composer require symfony/psr-http-message-bridge nyholm/psr7 annotations

config/packages/sensio:framework:extra.yaml

sensio_framework_extra:
    psr_message:
        enabled: true

If you are using Symfony Flex then the bundle will automatically be installed and the default configuration will be set. Otherwise you need to add it in your AppKernel.php file:

src/AppKernel.php

<?php

public function registerBundles()
{
    $bundles = [
        // ...
        new Webauthn\Bundle\WebauthnBundle(),
    ];
}

And add the Webauthn Route Loader:

config/routes/webauthn:routes.php

<?php

declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return function (RoutingConfigurator $routes) {
    $routes->import('.', 'webauthn');
};

Repositories

The first step is to create your credential and user entity repositories.

Only Doctrine ORM based repositories are provided. Other storage systems like filesystem or Doctrine ODM may be added in the future but, at the moment, you have to create these from scratch.

Configuration

You may also need to adjust other parameters.

If you don’t use Flex, hereafter an example of configuration file:

config/packages/webauthn.yaml

webauthn:
#    logger: null # PSR-3 compatible logging service
    credential_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialSourceRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
    user_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialUserEntityRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
    token_binding_support_handler: 'Webauthn\TokenBinding\IgnoreTokenBindingHandler' # We ignore the token binding instructions by default
    creation_profiles: # Authenticator registration profiles
        default: # Unique name of the profile
            rp: # Relying Party information
                name: '%env(Relying_PARTY_NAME)%' # CHANGE THIS! or create the corresponding env variable
                id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
#                icon: null # Secured image (data:// scheme)
#            challenge_length: 32
#            timeout: 60000
#            authenticator_selection_criteria:
#                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE
#                require_resident_key: false
#                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
#            extensions:
#                loc: true
#            public_key_credential_parameters: # You should not change this list
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_EdDSA #Order is important. Preferred algorithms go first
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256K
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES512
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS512
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS256
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS384
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS512
#            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE
    request_profiles: # Authentication profiles
        default: # Unique name of the profile
            rp_id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
#            challenge_length: 32
#            timeout: 60000
#            user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
#            extensions:
#                loc: true
#    metadata_service:
#        enabled: false
#        repository: 'App\Repository\MetadataStatementRepository'

Repositories

The credential_repository and user_repository parameters correspond to the services we created above.

Token Binding Handler

Please refer to this page. You should let the default value as it is.

Creation Profiles

If you don't create the creation_profiles section, a default profile is set.

Relying Party (rp)

The realying Party corresponds to your application. Please refer to this page for more information.

The parameter id is optional but highly recommended.

Challenge Length

By default, the length of the challenge is 32 bytes. You may need to select a smaller or higher length. This length can be configured for each profile:

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            challenge_length: 16

Timeout

The default timeout is set to 60 seconds (60 000 milliseconds). You can change this value as follows:

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            timeout: 30000

For v4.0+, the timeout will be set to null. The values recommended by the specification are as follow:

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)

Authenticator Selection Criteria

This set of options allows you to select authenticators depending on their capabilities. The values are described in the advanced concepts of the protocol.

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            authenticator_selection_criteria:
                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM
                require_resident_key: true
                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED

Public Key Credential Parameters

This option indicates the algorithms allowed for your application. By default, a large list of algorithms is defined, but you can add custom algorithms or reduce the list.

The order is important. Preferred algorithms go first.

It is not recommended changing the default list unless you exactly know what you are doing.

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            public_key_credential_parameters:
                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256

Attestation Conveyance

If you need the attestation of the authenticator, you can specify the preference regarding attestation conveyance during credential generation.

Please note that the metadata service is mandatory when you use this option.

The use of Attestation Statements is generally not recommended unless you REALLY need this information.

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT

Extensions

You can set as many extensions as you want in the profile. Please also refer to this page for more information.

The example below is totally fictive. Some extensions are defined in the specification but the support depends on the authenticators, on the browsers and on the relying parties (your applications).

app/config/webauthn.yaml

webauthn:
    creation_profiles:
        acme:
            rp:
                name: 'ACME Webauthn Server'
            extensions:
                loc: true
                txAuthSimple: 'Please add your new authenticator'

Request Profiles

If you don't create the creation_profiles section, a default profile is set.

app/config/webauthn.yaml

webauthn:
    request_profiles:
        acme:
            rp_id: 'example.com'

Please note that all parameters are optional. The following configuration is perfectly valid. However, and as mentioned above, the parameter id is highly recommended.

app/config/webauthn.yaml

webauthn:
    request_profiles:
        acme: ~

Firewall

Now you have a fully configured bundle, you can protect your routes and manage the user registration and authenticatin through the Symfony Firewall.

Firewall

How to register and authenticate my users?

Security Bundle

To authenticate or register your users with Symfony, the best and easiest way is to use the Security Bundle. First, install that bundle.

composer require symfony/security-bundle

Next, you have to create a custom user provider that will retrieve users on login requests. The following example uses the user repository showed on this page.

src/Repository/UserRepository.php

<?php

namespace App\Security;

use App\Entity\User;
use App\Repository\UserRepository;
use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\UserProviderInterface;

class UserProvider implements UserProviderInterface
{
    /**
     * @var UserRepository
     */
    private $userRepository;

    public function __construct(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    /**
     * @throws UsernameNotFoundException if the user is not found
     */
    public function loadUserByUsername($username): UserInterface
    {
        $user = $this->userRepository->find($username);
        if (null !== $user) {
            return $user;
        }

        throw new UsernameNotFoundException(sprintf('User with name "%s" does not exist', $username));
    }

    public function refreshUser(UserInterface $user): UserInterface
    {
        if (!$user instanceof User) {
            throw new UnsupportedUserException(sprintf('Invalid user class "%s".', get_class($user)));
        }

        return $this->loadUserByUsername($user->getUsername());
    }

    public function supportsClass($class): bool
    {
        return User::class === $class;
    }
}

Firewall Configuration

Now you can tell Symfony to use your user provider and you enable the dedicated firewall

config/packages/security.yaml

security:
    providers:
        main:
            id: 'App\Security\UserProvider'
    firewalls:
        main:
            webauthn: ~

In some case, you may have several user providers that are used by other parts of your application. This Webauthn bundle allow you to override the default user provider.

config/packages/security.yaml

security:
    providers:
        backend_users:
            memory:
                users:
                    john_admin: { password: '$2y$13$jxGxc ... IuqDju', roles: ['ROLE_ADMIN'] }
                    jane_admin: { password: '$2y$13$PFi1I ... rGwXCZ', roles: ['ROLE_ADMIN', 'ROLE_SUPER_ADMIN'] }
    firewalls:
        backend:
            pattern: ^/backend/
            # ... Add your configuration here
            
        main:
            webauthn:
                user_provider: 'App\Security\UserProvider'

Logout

Users can logout as usual. You just have to add the logout configuration under your firewall and add the route.

config/packages/security.yaml

security:
    # ...

    firewalls:
        main:
            # ...
            logout: ~

User Authentication

As you have noticed, there is nothing to configure to have a fully functional firewall. The firewall routes are automatically created for you. They are namely:

/login/options: to create the request options (POST only)
/login: to submit the assertion response (POST only)

You should also ensure to allow anonymous users to contact those endpoints.

security:
    access_control:
        - { path: ^/login,  roles: IS_AUTHENTICATED_ANONYMOUSLY }

Credential Request Options

Prior to the authentication of the user, you must create a PublicKey Credential Request Options object. To do so, send a POST request to /login/options.

The body of this request is a JSON object that must contain a username field with the name of the user being authenticated.

No need to reinvent the wheel, you can use the webauthn-helper package.

It is mandatory to set the Content-Type header to application/json.

fetch('/login/options', {
    method  : 'POST',
    credentials : 'same-origin',
    headers : {
        'Content-Type' : 'application/json'
    },
    body: JSON.stringify({
        "username": "johndoe@example.com"
    })
}).then(function (response) {
    return response.json();
}).then(function (json) {
    console.log(json);
}).catch(function (err) {
    console.log({ 'status': 'failed', 'error': err });
})

In case of success, you receive a valid PublicKeyCredentialRequestOptions object and your user will be asked to interact with one of its registered security devices.

The default path is /login/options. You can change it if needed:

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    routes:
                        options_path: /security/authentication/options
    access_control:
        - { path: ^/security/authentication/options,  roles: IS_AUTHENTICATED_ANONYMOUSLY}

Assertion Response

When the user touched the security device, you will receive a response from it. You just have to send a POST request to /login.

The body of this request is the response of the security device.

It is mandatory to set the Content-Type header to application/json.

fetch('/login', {
    method  : 'POST',
    credentials : 'same-origin',
    headers : {
        'Content-Type' : 'application/json'
    },
    body: //put the security device response here
}).then(function (response) {
    return response.json();
}).then(function (json) {
    console.log(json);
}).catch(function (err) {
    console.log({ 'status': 'failed', 'error': err });
})

The default path is /login. You can change that path if needed:

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    routes:
                        result_path: /security/authentication/login

Your user can now be authenticated and retrieved as usual.

Acme\Controller\AdminController.php

<?php

declare(strict_types=1);

namespace Acme\Controller;

use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;

final class AdminController
{
    /**
     * @var TokenStorageInterface
     */
    private $tokenStorage:

    public function __construct(TokenStorageInterface $tokenStorage)
    {
        $this->tokenStorage = $tokenStorage;
    }

    public function __invoke()
    {
        // $token is an object of type Webauthn\Bundle\Security\Authentication\Token\WebauthnToken
        $token = $this->tokenStorage->getToken();
        ...
    }
}

Request Profile

By default, the default profile is used. You may have created a request profile in the bundle configuration. You can use this profile instead of the default one.

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    profile: 'acme'

User Registration

The user registration is also managed by the firewall. It is disabled by default. If you want that feature, please enable it:

security:
    firewalls:
        main:
            webauthn:
                registration:
                    enabled: true

The firewall routes are automatically created for you. They are namely:

/register/options: to create the creation options (POST only)
/register: to submit the attestation response (POST only)

You should also ensure to allow anonymous users to contact those endpoints.

security:
    access_control:
        - { path: ^/register,  roles: IS_AUTHENTICATED_ANONYMOUSLY }

Credential Creation Options

Prior to the registration of a user and its authenticator, you must create a PublicKey Credential Creation Options object. To do so, send a POST request to /register/options.

The body of this request is a JSON object that must contain username and displayName fields with the username of the user being registered and the name displayed in the application.

It is mandatory to set the Content-Type header to application/json.

fetch('/register/options', {
        method  : 'POST',
        credentials : 'same-origin',
        headers : {
            'Content-Type' : 'application/json'
        },
        body: JSON.stringify({
            "username": "johndoe@example.com",
            "displayName": "John Doe"
        })
    }).then(function (response) {
        return response.json();
    }).then(function (json) {
        console.log(json);
    }).catch(function (err) {
        console.log({ 'status': 'failed', 'error': err });
    })

In case of success, you receive a valid PublicKeyCredentialCreationOptions object and your user will be asked to interact with its security device.

The default path is /register/options. You can change it if needed:

security:
    firewalls:
        main:
            webauthn:
                registration:
                    routes:
                        options_path: /security/registration/options
    access_control:
        - { path: ^/security/registration/options,  roles: IS_AUTHENTICATED_ANONYMOUSLY}

Attestation Response

When the user touched the security device, you will receive a response from it. You just have to send a POST request to /register.

The body of this request is the response of the security device.

It is mandatory to set the Content-Type header to application/json.

fetch('/register', {
    method  : 'POST',
    credentials : 'same-origin',
    headers : {
        'Content-Type' : 'application/json'
    },
    body: //put the security device response here
}).then(function (response) {
    return response.json();
}).then(function (json) {
    console.log(json);
}).catch(function (err) {
    console.log({ 'status': 'failed', 'error': err });
})

The default path is /register. You can change that path is needed:

security:
    firewalls:
        main:
            webauthn:
                registration:
                    routes:
                        result_path: /security/registration/result

In case of success, the user and the authenticator are correctly registered and automatically logged in.

Creation Profile

By default, the default profile is used. You may have created a creation profile in the bundle configuration. You can use this profile instead of the default one.

security:
    firewalls:
        main:
            webauthn:
                registration:
                    profile: 'acme'

Authentication Attributes

The security token returned by the firewall sets some attributes depending on the assertion and the capabilities of the authenticator. The attributes are:

IS_USER_PRESENT: the user was present during the authentication ceremony. This attribute is usually set to true by authenticators,
IS_USER_VERIFIED: the user was verified by the authenticator. Verification may be performed by several means including biometrics ones (fingerprint, iris, facial recognition…).

You can then set constraints to the access controls. In the example below, the /admin path can be reached by users with the role ROLE_ADMIN and that have been verified during the ceremony.

security:
    access_control:
        - { path: ^/admin,  roles: [ROLE_ADMIN, IS_USER_VERIFIED]}

Options Storage

Webauthn authentication and registration are 2 steps round trip processes:

Options issuance
Authenticator response verification

It is required to store the options and the user entity associated to it to verify the authenticator responses.

By default, the firewall uses Webauthn\Bundle\Security\Storage\SessionStorage. This storage system stores the data in a session.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                options_storage: 'App\Handler\MyCustomRequestOptionsStorage'

Response Handlers

You can customize the responses returned by the firewall by using a custom handler. This could be useful when you want to return additional information to your application.

There are 4 types of responses and handlers:

Request options,
Creation options,
Authentication Success,
Authentication Failure,

Request Options Handler

Your custom handler has to implement the interface Webauthn\Bundle\Security\Handler\RequestOptionsHandler and be declared as a service.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                authentication:
                    options_handler: 'App\Handler\MyCustomRequestOptionsHandler'

Creation Options Handler

ecurity:
    firewalls:
        main:
            webauthn:
                registration:
                    options_handler: 'App\Handler\MyCustomRequestOptionsHandler'

Authentication Success Handler

This handler is called when a client sends a valid assertion from the authenticator. The default handler is Webauthn\Bundle\Security\Handler\DefaultSuccessHandler.

Your custom handler has to implement the interface Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface and be declared as a container service.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                success_handler: 'App\Handler\MyCustomAuthenticationSuccessHandler'

Authentication Failure Handler

This handler is called when an error occurred during the authentication process. The default handler is Webauthn\Bundle\Security\Handler\DefaultFailureHandler.

Your custom handler has to implement the interface Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface and be declared as a container service.

When done, you can set your new service in the firewall configuration:

security:
    firewalls:
        main:
            webauthn:
                failure_handler: 'App\Handler\MyCustomAuthenticationFailureHandler'