WebAuthnAuthnConfiguration
- Philip Smart
- Tom Zeller
- Rod Widdowson
- Steven Premeau
Overview
The authn/WebAuthn login flow supports the Web Authentication API (WebAuthn) as part of the FIDO2 standard—enabling FIDO2 authentication. This allows public-key-based strong authentication of users. The plugin can operate as either a single-factor within a wider multi-factor authentication, as a sole-factor where the username is first supplied by the user (passwordless), or as a sole-factor where the username is not supplied by the user and is instead implicitly identified from the credential they choose (usernameless).
Plugin Installation
Enabling the Module
For a detailed guide on configuring modules, see the ModuleConfiguration topic. Once the plugin has been installed, its module should be enabled automatically for you:
Check Module Is Enabled
/%{idp.home}/bin$ ./module.sh -l
...
Module: idp.authn.WebAuthn [ENABLED]However, if you need to enable it you can using the module command:
Enable the module
/%{idp.home}/bin$ ./module.sh -e idp.authn.WebAuthnEither manual or automatic module enablement will copy across the following configuration files from the jar:
Configuration files
File | Description |
|---|---|
| Properties file for configuration of the plugin |
| Properties file for the configuration of the plugin’s registration admin flow |
| Properties file for the configuration of the plugin’s FIDO2 metadata handling |
| XML file for configuration of new beans for the plugin |
| XML file for configuration of new beans for the plugin’s registration admin flow |
| XML file for configuration of new beans for the plugin’s credential management admin flow |
| The authentication view |
| A username collection view for passwordless authentication |
| The credential registration view |
| A username collection view for the registration view |
| A user credential management view, for administrators |
| A user credential management search view, for administrators |
| A terminating view for all flows |
| Additional styling for the WebAuthn views |
| Javascript library that wraps the WebAuthn API for encoding binary data |
| Additional Javascript to support functions on the WebAuthn views |
Overview of Configuration Steps
Add the relyingPartyId to conf/authn/webauthn.properties
Add the relyingPartyName to conf/authn/webauthn.properties
Decide how the flow should be used for authentication.
Configure the MFA flow to use the WebAuthn authentication method
Add the MFA flow to the idp.authn.flows property in conf/authn/authn.properties.
Think about which Authentication Context Class (Supported Principals) the flow should expose
Register a FIDO2 credential through the registration admin flow
Decide if you want to enable support for authenticator metadata.
Show your administrator how to remove user credentials
Configure your auditing requirements.
Configuration of the WebAuthn Relying Party
The IdP acts as a WebAuthn Relying Party when initiating the Web Authentication API to register and authenticate users. The identity of the Relying Party (IdP) must be configured in conf/authn/webauthn.properties.
Required relyingPartyId: A valid domain string. Set to the IdP’s origin’s effective domain. FIDO2 credentials are scoped to, and can only be used for, a relying party. It does not include a scheme (it must be HTTPS) or port (as a normal origin would). Credentials are scoped to the Relying Party ID.
Note, ‘localhost’ can be used for testing.
Required relyingPartyName: a human-palatable identifier for the relying party. Used for display purposes.
Optional allowPortOrigin: If true, any port is allowed for the given origin.
Optional allowOriginSubdomain: If true, any subdomain (of any depth) is allowed for the given origin.
Optional allowOrigins: Comma-separated set of origins to allow in responses from an authenticator for this Relying Party. If not set, the Relying Party ID is used (assuming the HTTPS scheme and the default port 443). Note, unlike the Relying Party ID, this includes the scheme and port.