The Symfony Way

Search…
v3.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.
1
composer require symfony/psr-http-message-bridge nyholm/psr7 annotations
Copied!
config/packages/sensio:framework:extra.yaml
1
sensio_framework_extra:
2
    psr_message:
3
        enabled: true
Copied!
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
1
<?php
2
​
3
public function registerBundles()
4
{
5
    $bundles = [
6
        // ...
7
        new Webauthn\Bundle\WebauthnBundle(),
8
    ];
9
}
Copied!
And add the Webauthn Route Loader:
config/routes/webauthn:routes.php
1
<?php
2
​
3
declare(strict_types=1);
4
​
5
use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
6
​
7
return function (RoutingConfigurator $routes) {
8
    $routes->import('.', 'webauthn');
9
};
Copied!
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
1
webauthn:
2
#    logger: null # PSR-3 compatible logging service
3
    credential_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialSourceRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
4
    user_repository: 'Webauthn\Bundle\Repository\DummyPublicKeyCredentialUserEntityRepository' # CREATE YOUR REPOSITORY AND CHANGE THIS!
5
    token_binding_support_handler: 'Webauthn\TokenBinding\IgnoreTokenBindingHandler' # We ignore the token binding instructions by default
6
    creation_profiles: # Authenticator registration profiles
7
        default: # Unique name of the profile
8
            rp: # Relying Party information
9
                name: '%env(Relying_PARTY_NAME)%' # CHANGE THIS! or create the corresponding env variable
10
                id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
11
#                icon: null # Secured image (data:// scheme)
12
#            challenge_length: 32
13
#            timeout: 60000
14
#            authenticator_selection_criteria:
15
#                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE
16
#                require_resident_key: false
17
#                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
18
#            extensions:
19
#                loc: true
20
#            public_key_credential_parameters: # You should not change this list
21
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_EdDSA #Order is important. Preferred algorithms go first
22
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
23
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256K
24
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES384
25
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES512
26
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256
27
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS384
28
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS512
29
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS256
30
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS384
31
#                - !php/const Cose\Algorithms::COSE_ALGORITHM_PS512
32
#            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_NONE
33
    request_profiles: # Authentication profiles
34
        default: # Unique name of the profile
35
            rp_id: '%env(Relying_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
36
#            challenge_length: 32
37
#            timeout: 60000
38
#            user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
39
#            extensions:
40
#                loc: true
41
#    metadata_service:
42
#        enabled: false
43
#        repository: 'App\Repository\MetadataStatementRepository'
Copied!
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
1
webauthn:
2
    creation_profiles:
3
        acme:
4
            rp:
5
                name: 'ACME Webauthn Server'
6
            challenge_length: 16
Copied!
Timeout
The default timeout is set to 60 seconds (60 000 milliseconds). You can change this value as follows:
app/config/webauthn.yaml
1
webauthn:
2
    creation_profiles:
3
        acme:
4
            rp:
5
                name: 'ACME Webauthn Server'
6
            timeout: 30000
Copied!
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
1
webauthn:
2
    creation_profiles:
3
        acme:
4
            rp:
5
                name: 'ACME Webauthn Server'
6
            authenticator_selection_criteria:
7
                attachment_mode: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM
8
                require_resident_key: true
9
                user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_REQUIRED
Copied!
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
1
webauthn:
2
    creation_profiles:
3
        acme:
4
            rp:
5
                name: 'ACME Webauthn Server'
6
            public_key_credential_parameters:
7
                - !php/const Cose\Algorithms::COSE_ALGORITHM_ES256
8
                - !php/const Cose\Algorithms::COSE_ALGORITHM_RS256
Copied!
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
1
webauthn:
2
    creation_profiles:
3
        acme:
4
            rp:
5
                name: 'ACME Webauthn Server'
6
            attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT
Copied!
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
1
webauthn:
2
    creation_profiles:
3
        acme:
4
            rp:
5
                name: 'ACME Webauthn Server'
6
            extensions:
7
                loc: true
8
                txAuthSimple: 'Please add your new authenticator'
Copied!
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
1
webauthn:
2
    request_profiles:
3
        acme:
4
            rp_id: 'example.com'
Copied!
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
1
webauthn:
2
    request_profiles:
3
        acme: ~
Copied!
Firewall
Now you have a fully configured bundle, you can protect your routes and manage the user registration and authenticatin through the Symfony Firewall.
Authenticate Your Users
Entities with Doctrine
Last modified 1d ago
Export as PDF
Copy link
Contents
Repositories
Configuration
Repositories
Token Binding Handler
Creation Profiles
Request Profiles
Firewall