From 4.x to 5.0

Step-by-step guide for migrating from 4.x to 5.0

This page is subject to changes as the version 5.0.0 is not available at the time of writing.

This project follows the Semantic Versioning principles and, contrary to upgrade a minor version (where the middle number changes) where no difficulty should be encountered, upgrade a major version (where the first number changes) is subject to significant modifications.

Update the libraries

First of all, you have to make sure you are using the last 4.x release (4.8.0 at the time of writing).

In addition, you have to make sure you are using PHP 8.3+.

If you explicitly require web-auth/metadata-service, please remove it. All classes are now part of the main library

Spot deprecations

Next, you have to verify you don’t use any deprecated class, interface, method or property. If you have PHPUnit tests, you can easily get the list of deprecation used in your application.

PSR-20 Clock

In previous versions, the classes that requires time used the PHP time function directly. It is now required to use a PSR-20 Clock implementation and pass it to the classes.

• Webauthn\MetadataService\CertificateChain\PhpCertificateChainValidator

For version 3.2.0+ and the Symfony Bundle, an internal implementation service named jose.internal_clock existed and is removed.

Android SafetyNet

The Android SafetyNet API is deprecated and is completely removed in 5.0.

https://developer.android.com/privacy-and-security/safetynet/deprecation-timeline

Token Binding

All references to token binding are deprecated. This functionality is not supported anymore as removed from the latest Webauthn spectification versions.

ECDAA

All references to the ECDAA Attestation Statement type are deprecated. This functionality is not supported anymore as removed from the latest Webauthn spectification versions.

Webauthn\AuthenticatorSelectionCriteria

• Constant AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_NONE: please use AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_NO_PREFERENCE instead

Webauthn\CertificateToolbox

This class is now deprecated. Please use Webauthn\MetadataService\CertificateChainChecker\PhpCertificateChainValidator instead or a class that implements Webauthn\MetadataService\CertificateChain\CertificateChainValidator.

PublicKeyCredential Id and rawId

As these values are redundant, the Id property is deprecated in 4.9.0 and will be removed in 5.0.0.

Webauthn\PublicKeyCredentialLoader

This class is removed in 5.0. You should use Symfony Serializer or create a dedicated serializer using Webauthn\Denormalizer\WebauthnSerializerFactory.

Webauthn\PublicKeyCredentialSourceRepository

This interface is deprecated and removed. There is no replacement as it became useless for the library. The Symfony bundle uses its own interface Webauthn\Bundle\Repository\Webauthn\Bundle\Repository you are asked to use in the Symfony context.

Symfony Http Client

The PSR-17 and PSR-18 are not supported anymore. The library uses Symfony Http Client instead. A class is provided to help you to continue using PSR-* compatible libraries: Webauthn\MetadataService\Psr18HttpClient. This class is very basic and can be enhanced or overridden at will.

Events

The following events are removed in favor of events located in the library namespace:

• Webauthn\Bundle\Event\AuthenticatorAssertionResponseValidationFailedEvent

• Webauthn\Bundle\Event\AuthenticatorAssertionResponseValidationSucceededEvent

• Webauthn\Bundle\Event\AuthenticatorAttestationResponseValidationFailedEvent

• Webauthn\Bundle\Event\AuthenticatorAttestationResponseValidationSucceededEvent

Services

The following services are removed:

• webauthn.cose.algoritm.* (because of a typo)

• Webauthn\PublicKeyCredentialLoader

• Webauthn\PublicKeyCredentialSourceRepository

• Webauthn\TokenBinding\IgnoreTokenBindingHandler

• Webauthn\TokenBinding\SecTokenBindingHandler

• Webauthn\TokenBinding\TokenBindingNotSupportedHandler

Dependency Changes:

• Added:

  • symfony/clock

  • symfony/serializer

  • symfony/property-access

  • symfony/property-info

  • phpdocumentor/reflection-docblock

• Bumped:

  • PHP: >=8.2

  • symfony/*: ^6.4 or ^7.0

• Removed:

  • lcobucci/clock

Configuration Files

The following options are removed:

• webauthn.http_message_factory

• webauthn.token_binding_support_handler

• webauthn.creation_profiles[x].attachment_mode

Upgrade the libraries

When deprecations are removed, you can upgrade the libraries. In your composer.json, change all web-auth/* dependencies from ^4.x to ^5.0. When done, execute composer update.

This may also update other dependencies. You can list upgradable libraries by calling composer outdated. Please make sure these libraries do not impact your upgrade.

Doctrine Migration

These actions are only required if you use Doctrine and your public key credential source entity extends the one provided by the library.

When the libraries are up to date, you will need to perform a database migration.

The field type for transports and other_ui changed from array to json (array is now deprecated).

Hereafter an example of a Postgresql command:

ALTER TABLE [/*TABLE NAME HERE*/] ALTER transports TYPE JSON USING transports::JSON;
ALTER TABLE [/*TABLE NAME HERE*/] ALTER other_ui TYPE JSON USING other_ui::JSON;

Also, the trust path type key is not needed anymore and can be removed:

UPDATE pk_credential_sources SET trust_path = trust_path::jsonb - \'type\';

All Modifications In A Row

If you want to see all modifications at once, please have a look at this page.