Configuration references¶
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 variable RELYING_PARTY_ID.
You may also need to adjust other parameters.
If you don't use Flex, hereafter an example of configuration file:
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!
# allowed_origins: # List of allowed origins for WebAuthn operations (new in 5.2.0)
# - 'https://example.com'
# - 'https://app.example.com'
# - 'android:apk-key-hash://your-app-hash' # For Android FIDO2
# - 'ios:bundle-id://your.bundle.id' # For iOS
# allow_subdomains: false # Allow subdomains when validating origins (new in 5.2.0)
# ceremony_origin_pinning: false # Also require the response to come from the origin the ceremony started on (new in 5.4.0)
creation_profiles: # Authenticator registration profiles
default: # Unique name of the profile
rp: # Relying Party information
id: '%env(RELYING_PARTY_ID)%' # Please adapt the env file with the correct relying party ID or set null
# name: '%env(RELYING_PARTY_NAME)%' # Deprecated since 5.3.0. The serialized options default it to the rp ID
# icon: null # Secured image (data:// scheme)
# challenge_length: 32
# timeout: 60000
# hide_existing_credentials: false # Hide existing credentials during registration (new in 5.3.0)
# conditional_create: false # Enable Conditional Create for auto-registration (new in 5.3.0)
# authenticator_selection_criteria:
# authenticator_attachment: !php/const Webauthn\AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE
# require_resident_key: false
# user_verification: !php/const Webauthn\AuthenticatorSelectionCriteria::USER_VERIFICATION_REQUIREMENT_PREFERRED
# hints: [] # WebAuthn hints: security-key, client-device, hybrid (new in 5.3.0)
# 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
# client_override_policy: # Granular control over client overrides (new in 5.3.0)
# user_verification:
# enabled: true
# allowed_values: ['required', 'preferred', 'discouraged']
# authenticator_attachment:
# enabled: true
# allowed_values: ['platform', 'cross-platform']
# resident_key:
# enabled: true
# allowed_values: ['required', 'preferred', 'discouraged']
# attestation_conveyance:
# enabled: true
# allowed_values: ['none', 'indirect', 'direct', 'enterprise']
# extensions:
# enabled: true
# mediation: # Opt-in: let the client request a Conditional Create flow
# enabled: false
# allowed_values: ['default', 'conditional']
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
# hints: [] # WebAuthn hints: security-key, client-device, hybrid (new in 5.3.0)
# extensions:
# loc: true
# passkey_endpoints: # .well-known/passkey-endpoints discovery (new in 5.3.0)
# enabled: false
# enroll: 'https://example.com/passkeys/register'
# manage: 'https://example.com/passkeys/manage'
# prf_usage_details: 'https://example.com/passkeys/prf-info'
# metadata:
# enabled: false
# mds_repository: 'App\Repository\MetadataStatementRepository'
# status_report_repository: 'App\Repository\StatusReportRepository'
# certificate_chain_checker: 'App\Security\CertificateChainChecker'
Creation profiles¶
Success
If you don't create the creation_profiles section, a default profile is set.
Relying party (rp)¶
The Relying Party corresponds to your application. Please refer to this page for more information.
Warning
The parameter id is optional but highly recommended.
Info
The parameters name and icon are deprecated (since 5.3.0 and 5.1.0 respectively) and are removed in 6.0.0. Since 5.3.7, a profile without rp.name produces options where the name member defaults to the Relying Party ID, and no deprecation is triggered.
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:
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:
webauthn:
creation_profiles:
acme:
rp:
name: 'ACME WebAuthn Server'
timeout: 30000
Info
For v4.0+, the timeout is set to null. The values recommended by the specification are as follows:
- If the user verification is
discouraged, timeout should be between 30 and 180 seconds - If the user verification is
preferredorrequired, the range is 300 to 600 seconds (5 to 10 minutes)
These behaviors are not necessarily followed by the web browsers.
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.
webauthn:
creation_profiles:
acme:
rp:
name: 'ACME WebAuthn Server'
authenticator_selection_criteria:
authenticator_attachment: !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.
Info
The order is important. Preferred algorithms go first.
Warning
It is not recommended to change the default list unless you exactly know what you are doing.
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
Signature verification algorithms¶
The parameters above list the algorithms offered to the authenticator during the registration. The signatures themselves are verified by webauthn.cose.algorithm.manager, which the bundle fills with one service per supported algorithm. Any service implementing Cose\Algorithm\Algorithm is collected automatically, so declaring one is enough to add an algorithm to that manager.
Danger
Backward compatibility break in v5.3.8: the bundle no longer registers RS1 (RSASSA-PKCS1-v1_5 with SHA-1). SHA-1 is no longer acceptable for digital signatures, and building the algorithm emits an E_USER_WARNING that the Symfony error handler turns into an exception, so every ceremony answered with a 500 in the dev environment.
RS1 was never offered at the registration, as public_key_credential_parameters is empty by default. The applications that added Cose\Algorithms::COSE_ALGORITHM_RS1 to that list are the only ones affected: without the service, the assertions signed by the credentials they registered are rejected.
If you are in that situation, declare the algorithm yourself. Autoconfiguration adds it back to the manager.
services:
webauthn.cose.algorithm.RS1:
class: Cose\Algorithm\Signature\RSA\RS1
arguments:
- true # Acknowledge that the algorithm is insecure
Attestation conveyance¶
If you need the attestation of the authenticator, you can specify the preference regarding attestation conveyance during credential generation.
Warning
The use of Attestation Statements is generally not recommended unless you REALLY need this information.
webauthn:
creation_profiles:
acme:
rp:
name: 'ACME WebAuthn Server'
attestation_conveyance: !php/const Webauthn\PublicKeyCredentialCreationOptions::ATTESTATION_CONVEYANCE_PREFERENCE_DIRECT
Hints¶
Info
New in v5.3.0: Support for WebAuthn hints to guide user authentication choices.
Hints provide guidance to the user agent about how the user might authenticate. This can help improve the user experience by suggesting the most appropriate authentication method.
webauthn:
creation_profiles:
acme:
rp:
name: 'ACME WebAuthn Server'
hints:
- 'security-key'
- 'client-device'
- 'hybrid'
request_profiles:
acme:
rp_id: 'example.com'
hints:
- 'security-key'
- 'client-device'
Available hint values:
- security-key: External security key (like YubiKey)
- client-device: Platform authenticator (like Touch ID, Windows Hello)
- hybrid: Hybrid transport (like phone as authenticator)
Hide existing credentials¶
Info
New in v5.3.0: Exposed in bundle configuration.
When set to true, the server will automatically add the user's existing credentials to the excludeCredentials list in the creation options. This prevents the user from re-registering the same authenticator.
webauthn:
creation_profiles:
acme:
rp:
name: 'ACME WebAuthn Server'
hide_existing_credentials: true
Conditional create¶
Info
New in v5.3.0
Enable Conditional Create (auto-register) for a profile. When true, user presence can be false during registration, allowing silent credential creation after the user has authenticated via another method (e.g., password).
webauthn:
creation_profiles:
passkey_upgrade:
rp:
id: 'example.com'
conditional_create: true
authenticator_selection_criteria:
require_resident_key: true
See Conditional Create for detailed usage.
Client override policy¶
Info
New in v5.3.0
Control which WebAuthn options can be overridden by client request parameters. See Client Override Policy for detailed configuration.
webauthn:
creation_profiles:
acme:
rp:
id: 'example.com'
client_override_policy:
user_verification:
enabled: true
allowed_values: ['required', 'preferred']
authenticator_attachment:
enabled: false # Prevent client override
Extensions¶
You can set as many extensions as you want in the profile. Please also refer to this page for more information.
Info
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).
webauthn:
creation_profiles:
acme:
rp:
name: 'ACME WebAuthn Server'
extensions:
loc: true
txAuthSimple: 'Please add your new authenticator'
Request profiles¶
Success
If you don't create the request_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).
Please note that all parameters are optional. The following configuration is perfectly valid. However, and as mentioned above, the parameter id is highly recommended.
Passkey endpoints¶
Info
New in v5.3.0
Enable the .well-known/passkey-endpoints discovery endpoint. See Passkey Endpoints for detailed configuration.