Version 5 supported

WebAuthn authenticator

Installation

composer require silverstripe/webauthn-authenticator

What is web authentication (WebAuthn)?

We use the web-auth/webauthn-framework PHP library to provide support for the Web Authentication protocol:

Webauthn defines an API enabling the creation and use of strong, attested, scoped, public key-based credentials by web applications, for the purpose of strongly authenticating users.

This module is a Silverstripe wrapper for implementing this library, and provides the frontend UI components to work with the silverstripe/mfa module.

For more information about WebAuthn, see the Guide to Web Authentication.

Configuration

"Find out more" links

You can configure (or remove) the "help" links shown to users when the "Security key" authentication method option is shown in multi-factor authentication registration or verification flows by adjusting the user help link in configuration:

SilverStripe\WebAuthn\RegisterHandler:
  user_help_link: 'http://intranet.mycompany.com/help/how-to-use-mfa'

Authenticator selection criteria

The way the Webauthn\AuthenticatorSelectionCriteria instance is configured will define how appropriate authenticators are selected to participate in the creation operation of WebAuthn attestations. It has three settings, which are explained in the MDN web docs for authenticatorSelection.

The Silverstripe WebAuthn module allows you to configure the authenticatorAttachment option, which is responsible for determining whether single or cross-platform authenticators can be used in the registration operation. The default is that devices must be cross-platform (e.g. security keys) while single-platform devices (e.g. touch ID on mobile phones) are disabled. You can adjust this setting by configuring RegisterHandler.authenticator_attachment to use one of these options:

  • AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_NO_PREFERENCE: allows either
  • AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_PLATFORM: single-platform only
  • AuthenticatorSelectionCriteria::AUTHENTICATOR_ATTACHMENT_CROSS_PLATFORM: cross-platform only

For more information, see Authenticator Selection Criteria

Compatibility with subsites

This module is not recommended for use if your project has the silverstripe/subsites module installed.

The WebAuthn protocol includes security measures that will only allow the creation of a credential for per single domain or subdomain. Subsites that have a login form served over a different domain will not be compatible.

This restriction is a requirement of the WebAuthn Relying Party Entity.

Edit on Github