From 5.3 to 5.4¶
Success
No backward compatibility break. The YAML sections deprecated below keep working until 6.0.0. The only exception concerns the applications overriding the type of the counter column of the Doctrine mapping, see the counter column.
Version 5.4 is the preparation step for 6.0: the profile-driven YAML configuration of the Symfony bundle is superseded by autowired helpers called from controllers you write yourself. The whole configuration surface that goes away in 6.0 is deprecated here, so you can migrate progressively while staying on the 5.x line.
Database schema: the new rpId column¶
Warning
Action required if you persist your credentials with Doctrine
Version 5.4 adds the OPTIONAL rpId member of the credential record structure (see w3c/webauthn#2258). It stores the Relying Party ID the credential was scoped to during the registration ceremony, which is useful to the Relying Parties adopting Related Origin Requests.
The column is nullable, so the existing rows are left untouched:
Or, with the Doctrine Migrations bundle:
The records created before 5.4, and those created from creation options without an explicit rp.id, keep rpId set to null. The serialized payloads without the rpId key are still accepted, and the member is omitted from the serialized output when it is null.
Database schema: the counter column¶
Warning
Action required if your entity extends Webauthn\CredentialRecord
The signature counter is an unsigned 32-bit integer, but the Doctrine mapping of the bundle declared a signed INT column: the counters above 2147483647 could not be stored. The mapping now declares a BIGINT column, so the migration generated for the rpId column also contains:
-- MySQL
ALTER TABLE my_credential CHANGE counter counter BIGINT NOT NULL;
-- PostgreSQL
ALTER TABLE my_credential ALTER counter TYPE BIGINT;
Doctrine refuses an attribute override changing the type of an inherited field. If your entity overrides the counter column with an explicit type, for instance to add the unsigned option, drop the type from the override or the override itself:
// Refused since 5.4.0: the mapping declares a bigint
#[ORM\AttributeOverrides([
new ORM\AttributeOverride(name: 'counter', column: new ORM\Column(type: 'integer', options: ['unsigned' => true])),
])]
// Accepted
#[ORM\AttributeOverrides([
new ORM\AttributeOverride(name: 'counter', column: new ORM\Column(options: ['unsigned' => true])),
])]
The mapping itself is deprecated, see below.
Deprecations¶
Profile-driven configuration superseded by helpers¶
Warning
Deprecated in v5.4.0
The profile- and controller-driven YAML sections are superseded by the autowired helpers introduced in 5.4. Every section keeps working until 6.0; this section lists the migration path for each. See Options Helpers and Verification Helpers for the complete reference.
webauthn.creation_profiles / webauthn.request_profiles¶
Move to the WebauthnOptionsResponse helper from a controller of your own.
# Before (deprecated)
webauthn:
creation_profiles:
default:
rp:
id: 'example.com'
challenge_length: 32
authenticator_selection_criteria:
user_verification: 'preferred'
resident_key: 'preferred'
attestation_conveyance: 'none'
request_profiles:
default:
rp_id: 'example.com'
user_verification: 'preferred'
// After
use Webauthn\AuthenticatorSelectionCriteria;
use Webauthn\Bundle\Service\WebauthnOptionsResponse;
#[Route('/webauthn/register/options', methods: ['POST'])]
public function __invoke(Request $request): JsonResponse
{
return $this->options
->forCreation('example.com', $this->newUserGuesser)
->withChallengeLength(32)
->withAuthenticatorSelectionCriteria(
AuthenticatorSelectionCriteria::create(
AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE,
AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED,
AuthenticatorSelectionCriteria::RESIDENT_KEY_REQUIREMENT_PREFERRED,
)
)
->build($request);
}
webauthn.controllers¶
Replace each controllers.creation[name] and controllers.request[name] block by a pair of user controllers, one for the options endpoint and one for the response endpoint. The routes move to #[Route] attributes; the per-controller host, allowed_origins, allow_subdomains, hide_existing_credentials, user_entity_guesser and the other options all have a direct with*() equivalent on the helpers.
The full refactored example is on the Verification Helpers page.
webauthn.client_override_policy¶
Build a ClientOverridePolicy inline in the controller and attach it to the helper. 5.4 ships a typed ClientOverrideRule value object that makes the call site much clearer than the legacy nested-array form (both shapes stay supported as first-class APIs):
# Before (deprecated)
webauthn:
client_override_policy:
user_verification:
enabled: true
allowed_values: [preferred, required]
// After (5.4), typed factory recommended
use Webauthn\Bundle\Policy\ClientOverridePolicy;
use Webauthn\Bundle\Policy\ClientOverrideRule;
return $this->options
->forRequest('example.com')
->withClientOverrides(ClientOverridePolicy::fromRules(
userVerification: ClientOverrideRule::restrictTo(['preferred', 'required']),
))
->build($request);
// Or the legacy nested-array form, also first-class
return $this->options
->forRequest('example.com')
->withClientOverrides(new ClientOverridePolicy([
'user_verification' => [
'enabled' => true,
'allowed_values' => ['preferred', 'required'],
],
]))
->build($request);
webauthn.allowed_origins / webauthn.allow_subdomains¶
Two migration paths, depending on your topology.
Single-origin app (most common): drop the YAML node entirely. The verifier falls back to the W3C-recommended same-origin check against the request host. Nothing else to do.
Multi-origin app: inject a Symfony parameter into the helper.
# Before (deprecated)
webauthn:
allowed_origins:
- 'https://app.example.com'
- 'https://admin.example.com'
allow_subdomains: true
# After, in config/services.yaml
parameters:
app.webauthn.origins:
- 'https://app.example.com'
- 'https://admin.example.com'
// After, in every verification controller
use Symfony\Component\DependencyInjection\Attribute\Autowire;
public function __construct(
private readonly WebauthnResponseVerifier $verifier,
#[Autowire('%app.webauthn.origins%')]
private readonly array $origins,
) {}
#[Route('/webauthn/register', methods: ['POST'])]
public function __invoke(Request $request): Response
{
$result = $this->verifier
->forAttestation('example.com')
->withAllowedOrigins($this->origins)
->withAllowSubdomains(true)
->verify($request);
// ...
}
The list lives in a single Symfony parameter, the security-critical decision is visible right where it applies, and the per-route overrides become trivial.
Doctrine mapping of the bundle¶
Warning
Deprecated in v5.4.0
The bundle maps Webauthn\CredentialRecord, Webauthn\PublicKeyCredentialUserEntity and Webauthn\PublicKeyCredentialEntity as Doctrine mapped superclasses. That mapping only served DoctrineCredentialSourceRepository, deprecated since 5.2.0, and is removed in 6.0.0. A deprecation is triggered for each entity extending one of these classes, when Doctrine loads its metadata:
Since web-auth/webauthn-symfony-bundle 5.4.0: The entity "App\Entity\WebauthnCredential" extends "Webauthn\CredentialRecord" and relies on the Doctrine mapping provided by the bundle. This mapping is deprecated and will be removed in 6.0.0. Map an entity of your application and convert it from and to "Webauthn\CredentialRecord" in your repository instead.
Map an entity of your application and convert it from and to CredentialRecord in your repository, as shown in Credential Record Repository. That entity declares the same properties as CredentialRecord, so it keeps your table: once the migration above has run, the switch requires no schema change. An entity that does not extend these classes is not concerned, even though the mapping is still registered.
The user entity is already documented this way: see User Entity Repository.
Reserved-for-future-use accessors¶
Warning
Deprecated in v5.4.0
The RFU1 and RFU2 bits of the authenticator data flags are reserved by the specification and are set to zero by the authenticators, so reading them back brings nothing to a Relying Party. The accessors exposing them are removed in 6.0.0:
Webauthn\AuthenticatorData::getReservedForFutureUse1()andgetReservedForFutureUse2()Webauthn\Bundle\Security\Authentication\Token\WebauthnToken::getReservedForFutureUse1()andgetReservedForFutureUse2()- the
$reservedForFutureUse1and$reservedForFutureUse2arguments of theWebauthnTokenconstructor
Nothing changes at runtime in 5.4: the constructor signature, the stored values and the serialized payload are untouched, and a deprecation notice is emitted only when a getter is called. Drop the calls, there is no replacement. The raw flags byte stays available:
Use isBackupEligible() and isBackedUp() to read the backup flags.
Danger
In 6.0.0 the serialized payload of WebauthnToken loses two entries, so a session created by a 5.x application cannot be unserialized by a 6.0 one. Plan to invalidate the existing sessions when you upgrade.
PseudoRandomFunctionInputExtensionBuilder::requiresHmacSecretMc¶
Warning
Deprecated in v5.4.0
The method named the CTAP hmac-secret-mc extension in an API that is abstract over the authenticator implementation. Use requiresMultipleCredentialEvaluation(), which describes the input shape the method actually detects. The old name delegates to the new one until 6.0.0. See the PRF Extension page.
Other changes¶
Opt-in features, nothing to do on your side unless you want them:
- Ceremony origin pinning: the options request records its own origin next to the challenge, and the verifier can require the response to be produced on that very origin, on top of the allow list. Enable it with
withCeremonyOriginPinning()or thewebauthn.ceremony_origin_pinningnode. It fails closed on a ceremony stored without an origin, which is why it defaults tofalse. See Verification Helpers. - Related Origin Requests: the
/.well-known/webauthnendpoint warns when the published origins resolve to more than five distinct eTLD+1 labels, because the clients silently ignore the extra ones. Configure it underwebauthn.related_origins. - Signal API helpers: a factory and a JSON envelope for the WebAuthn Level 3 signal methods. See Signal API.
- CTAP 2.1 authenticator extensions:
credProtect,credBlob,getCredBlobandminPinLength. See Authenticator Extensions. - Fully-specified COSE algorithm identifiers from RFC 9864 are accepted.
- Immediate mediation is supported on
navigator.credentials.get(), and the Stimulus controllers use the nativeparseCreationOptionsFromJSON,parseRequestOptionsFromJSONandtoJSONhelpers along withPublicKeyCredential.getClientCapabilities().