Title here
Summary here
WebAuthn
Configuration
Example Configuration
This section is intended as an example configuration to help users with a rough contextual layout of this configuration section, it is not intended to explain the options. The configuration shown may not be a valid configuration, and you should see the options section below and the navigation links to properly understand each option individually.
webauthn:
disable: false
enable_passkey_login: false
display_name: 'Authelia'
attestation_conveyance_preference: 'indirect'
timeout: '60 seconds'
filtering:
permitted_aaguids: []
prohibited_aaguids: []
prohibit_backup_eligibility: false
selection_criteria:
attachment: ''
discoverability: 'preferred'
user_verification: 'preferred'
metadata:
enabled: false
validate_trust_anchor: true
validate_entry: true
validate_entry_permit_zero_aaguid: false
validate_status: true
validate_status_permitted: []
validate_status_prohibited:
- 'REVOKED'
- 'USER_KEY_PHYSICAL_COMPROMISE'
- 'USER_KEY_REMOTE_COMPROMISE'
- 'USER_VERIFICATION_BYPASS'
- 'ATTESTATION_KEY_COMPROMISE'Options
This section describes the individual configuration options.
disable
boolean
false
not required
This disables WebAuthn if set to true.
enable_passkey_login
boolean
false
not required
Enables login via a Passkey instead of a username and password. This login only counts as a single factor. The user will be prompted for their password by default if the request requires multi-factor authentication.
experimental_enable_passkey_uv_two_factors
Stability and Security Notice
This option is not considered supported. It is completely experimental and will be replaced by custom policies that can be defined in the access control section and allow deterministic results for authentication. This is in an effort to properly support Authentication Method Reference Values for authentication flows. The likely versions this will release in will be detailed in the roadmap item (specifically at the time we add the flow to replace this) that this option will cause a startup failure.
This option allows for authenticators that enforce user verification (PIN entry, biometric proof, etc) and reports they
have performed user verification, to satisfy the two_factor policy for access control rules.
display_name
string
Authelia
not required
Sets the display name which is sent to the client to be displayed. It’s up to individual browsers and potentially individual operating systems if and how they display this information.
See the W3C WebAuthn Documentation for more information.
attestation_conveyance_preference
string
indirect
not required
Sets the conveyance preference. Conveyancing allows collection of attestation statements about the authenticator such as the AAGUID. The AAGUID indicates the model of the authenticator.
See the W3C WebAuthn Documentation for more information.
Available Options:
| Value | Description |
|---|---|
| none | The client will be instructed not to perform conveyancing |
| indirect | The client will be instructed to perform conveyancing but the client can choose how to do this including using a third party anonymization CA |
| direct | The client will be instructed to perform conveyancing with an attestation statement directly signed by the authenticator |
timeout
Reference Note
This configuration option uses a common syntax. For more information please see both the configuration example and the Common Syntax: Duration reference guide.
This adjusts the requested timeout for a WebAuthn interaction.
filtering
This section configures various filtering options during registration.
permitted_aaguids
list(string)
uuid
not required
A list of Authenticator Attestation GUID’s that are the only ones allowed to be registered. Useful if you have a company policy that requires certain authenticators. Mutually exclusive with prohibited_aaguids.
prohibited_aaguids
list(string)
uuid
not required
A list of Authenticator Attestation GUID’s that users will not be able to register. Useful if company policy prevents certain authenticators. Mutually exclusive with permitted_aaguids.
prohibit_backup_eligibility
boolean
false
not required
Setting this value to true will ensure Authenticators which can export credentials will not be able to register. This will likely prevent synchronized credentials from being registered.
selection_criteria
The selection criteria options set preferences for selecting a suitable authenticator.
attachment
string
not required
Sets the attachment preference for newly created credentials.
Available Options:
| Value | Description |
|---|---|
| empty | The Authenticators that are available will be shown and the user can pick the specific criteria |
| cross-platform | Authenticators that can move from one system to another such as physical security keys |
| platform | Authenticators that are part of the platform such as Windows Hello, AppleID, etc |
discoverability
string
preferred
not required
Sets the discoverability preference. May affect the creation of Passkeys.
| Value | Description |
|---|---|
| discouraged | Prefers no discoverability |
| preferred | Prefers discoverability and will not error if it’s not discoverable |
| required | Requires discoverability and may error if it’s not discoverable |
user_verification
string
preferred
not required
Sets the user verification preference.
See the W3C WebAuthn Documentation for more information.
Available Options:
| Value | Description |
|---|---|
| discouraged | The client will be discouraged from asking for user verification |
| preferred | The client if compliant will ask the user for verification if the authenticator supports it |
| required | The client will ask the user for verification or will fail if the authenticator does not support verification |
metadata
Configures the metadata service which is used to check the authenticity of authenticators. Useful if company policy requires only conformant authenticators.
See the reference guide for the recommended configuration.
enabled
boolean
false
not required
Enables metadata service validation of authenticators and credentials. This requires the download of the metadata service blob which will utilize about 5MB of data in your configured storage backend.
By default to prevent breaking changes this value is false. It’s recommended however users take the time to configure it now that it’s available.
validate_trust_anchor
boolean
true
not required
Enables validation of the attestation certificate against the Certificate Authority certificate in the validated MDS3 blob. It’s recommended this value is always the default value.
validate_entry
boolean
true
not required
Enables validation that an entry exists for the authenticator in the MDS3 blob. It’s recommended that this option is the default value, however this may exclude some authenticators which DO NOT have FIDO compliance certification or have otherwise not registered with the MDS3. The recommendation is based on the fact that the authenticity of a particular authenticator cannot be validated without this.
validate_entry_permit_zero_aaguid
boolean
false
not required
Allows authenticators which have provided an empty Authenticator Attestation GUID. This may be required for certain authenticators which DO NOT have FIDO compliance certification.
validate_status
boolean
true
not required
Enables validation of the attestation entry statuses. There is generally never a reason to disable this as the authenticators excluded by default are likely compromised.
validate_status_permitted
list(string)
not required
A list of exclusively required statuses for an authenticator to pass validation. See the reference guide for information on valid values.
validate_status_prohibited
list(string)
not required
A list of authenticator statuses which for an authenticator that are prohibited from being registered. See the reference guide for information on valid values. It’s strongly recommended not changing the default value.
The default configuration for this option is as per the Configuration example above.
Frequently Asked Questions
See the Security Key FAQ for the FAQ.
Next
Security