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 single-factor where the username is supplied by the user (passwordless flow), or as a single-factor where the username is not supplied by the user (usernameless flows using passkeys).

Plugin Installation

Plugin	Plugin ID	Module(s)	Depends On	Authentication Flow ID	Latest Version	Bug Reporting

Plugin	Plugin ID	Module(s)	Depends On	Authentication Flow ID	Latest Version	Bug Reporting
WebAuthn Authentication Plugin	net.shibboleth.idp.plugin.authn.webauthn	idp.authn.WebAuthn		authn/WebAuthn	0.9.0-RC2	JWEBAUTHN

Installation of Pre-release Plugin

In summary, use the plugin command that ships with the IdP to install the plugin from either a local file pre-downloaded from https://shibboleth.net/downloads/prerelease/ or directly via the pluggin URL.

Note: during the Alpha phase, the --noCheck option is required for successful installation.

Installation

C:>\opt\shibboleth-idp\bin\plugin.bat --noCheck -i https://shibboleth.net/downloads/prerelease/idp-plugin-webauthn-0.0.2.tar.gz

or

$ /opt/shibboleth-idp/bin/plugin.sh --noCheck -i https://shibboleth.net/downloads/prerelease/idp-plugin-webauthn-0.0.2.tar.gz

or

$ /opt/shibboleth-idp/bin/plugin.sh --noCheck -i <plugin.tar.gz>

If installing from a local file, you need to ensure the GPG detached signature (e.g. the .asc file) is placed alongside the main plugin archive on disk.

If it has not been seen before, you will be asked to accept the key signing that signed the module into the trust store for this plugin. See PluginTrust for more information on how to ensure the contents of the plugin have not been modified.

Listing Installed Plugins

$ /opt/shibboleth-idp/bin/plugin.sh -l

or

C:>\opt\shibboleth-idp\bin\plugin.bat -l

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.WebAuthn

Either manual or automatic module enablement will copy across the following configuration files from the jar:

Configuration files

File	Description

File	Description
`conf/authn/webauthn.properties`	Properties file for configuration the plugin
`conf/authn/webauthn-config.xml`	XML file for configuration of new beans for the plugin
`views/webauthn/webauthn-authn.vm`	The authentication view
`views/webauthn/webauthn-authn-username.vm`	A username view for passwordless authentication
`views/webauthn/webauthn-register.vm`	The FIDO2 credential registration view
`views/webauthn/webauthn-register-username.vm`	A username view for the registration view
`edit-webapp/css/webauthn.css`	Additional styling for the WebAuthn views
`edit-webapp/js/webauthn-json.browser-ponyfill.js`	Javascript library that wraps the WebAuthn API for encoding binary data
`edit-webapp/js/webauthn-support.js`	Additional Javascript to support functions on the WebAuthn views

Overview of Configuration Steps

Configure the plugin
- Add the relyingPartyId to conf/authn/webauthn.properties
- Add the relyingPartyName to conf/authn/webauthn.properties
Decide how the flow should be used.
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
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.

The 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 or port (as a normal origin would). Credentials are scoped to the Relying Party ID.
- Note, ‘localhost’ can be used for testing.
The 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). Note, unlike the Relying Party ID, this includes the scheme and port.

# The IdP's origin
idp.authn.webauthn.relyingPartyId = localhost
idp.authn.webauthn.relyingPartyName = My IdP Name
# Allow any port of 'localhost'
idp.authn.webauthn.allowOriginPort = true
# Do not allow any subdomain of 'localhost'
idp.authn.webauthn.allowOriginSubdomain = false

Identity Provider Plugins

WebAuthnAuthnConfiguration