Webauthn Framework
v4.8
v4.8
  • WebAuthn: Strong Authentication for your PHP applications
  • The project
    • What is Webauthn?
    • Web Browser Support
    • Installation
    • Contributing
  • Webauthn In A Nutshell
    • Authenticators
    • Ceremonies
    • User Verification
    • Metadata Statement
    • Extensions
  • Prerequisites
    • The Relying Party
    • Credential Source
    • User Entity
    • Javascript
  • Pure PHP
    • Webauthn Server
    • Input Loading
    • Input Validation
    • Register Authenticators
    • Authenticate Your Users
    • Advanced Behaviours
      • Debugging
      • User Verification
      • Authenticator Selection Criteria
      • Authentication without username
      • Authenticator Algorithms
      • Attestation and Metadata Statement
      • Extensions
      • Authenticator Counter
      • Dealing with “localhost”
  • Symfony Bundle
    • Bundle Installation
    • Credential Source Repository
    • User Entity Repository
    • Firewall
    • Configuration References
    • Advanced Behaviors
      • Register Additional Authenticators
      • Debugging
      • User Verification
      • Attestation and Metadata Statement
      • Authenticator Selection Criteria
      • Authentication without username
      • Extensions
      • Authenticator Counter
      • Dealing with “localhost”
  • Migration
    • From v3.x to v4.0
    • From 4.x to 5.0
  • Symfony UX
    • Installation
    • Integration
Powered by GitBook
On this page
  • Security Bundle
  • User Authentication
  • Request Profile
  • User Registration
  • Authentication Attributes
  • Response Handlers
  • Request Options Handler
  • Creation Options Handler
  • Authentication Success Handler
  • Authentication Failure Handler

Was this helpful?

Edit on GitHub
Export as PDF
  1. Symfony Bundle

Firewall

How to register and authenticate my users?

PreviousUser Entity RepositoryNextConfiguration References

Last updated 1 year ago

Was this helpful?

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 and follow the instructions given by .

At the end of the installation and configuration, you should have a config/packages/security.yaml file that looks like as follow:

config/packages/security.yaml
security:
    providers:
        default:
            id: App\Security\UserProvider
    firewalls:
        main:
            logout:
                path: 'logout'
            ...

User Authentication

To enable the user authentication, you just have to declare the webauthn authenticator if the appropriate firewall (here main).

config/packages/security.yaml
security:
    providers:
        default:
            id: App\Security\UserProvider
    firewalls:
        main:
            webauthn: ~
            logout:
                path: '/logout'
    access_control:
        - { path: ^/login,  roles: PUBLIC_ACCESS, requires_channel: 'https'}
        - { path: ^/logout,  roles: PUBLIC_ACCESS}

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)

If you need, you can customize those endpoints.

config/packages/security.yaml
security:
    firewalls:
        main:
            webauthn:
                authentication:
                    routes:
                        options_path: '/assertion/options'
                        result_path: '/assertion/result'

    access_control:
        - { path: ^/assertion,  roles: PUBLIC_ACCESS, requires_channel: 'https'}

Request Profile

config/packages/security.yaml
security:
    firewalls:
        main:
            webauthn:
                authentication:
                    profile: 'acme'

User Registration

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

config/packages/security.yaml
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.

config/packages/security.yaml
security:
    access_control:
        - { path: ^/register,  roles: PUBLIC_ACCESS}

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.

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

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: options returned during the authentication ceremony,

  • Creation options: options returned during the registration ceremony,

  • 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:

config/packages/security.yaml
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.

config/packages/security.yaml
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:

config/packages/security.yaml
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:

config/packages/security.yaml
security:
    firewalls:
        main:
            webauthn:
                failure_handler: 'App\Handler\MyCustomAuthenticationFailureHandler'

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

the official documentation
Configuration References