A simple self-contained demo server supporting multiple authenticators per user. It illustrates how to use the required integration points, the most important of which is the user and credential registration storage, and also illustrates how one can perform auxiliary actions such as adding an additional authenticator or deregistering a credential.
``` $ ./gradlew run $ $BROWSER https://localhost:8443/ ```
The example webapp is made up of three main layers, the bottom of which is the
The front end interacts with the server via a REST API, implemented in WebAuthnRestResource.
This layer manages translation between JSON request/response payloads and domain objects, and most methods simply call into analogous methods in the server layer.
The REST API then delegates to the server layer, implemented in WebAuthnServer.
This layer manages the general architecture of the system, and is where most business logic and integration code would go. The demo server implements the "persistent" storage of users and credential registrations - the CredentialRepository integration point - as the InMemoryRegistrationStorage class, which simply keeps them stored in memory for a limited time. The transient storage of pending challenges is also kept in memory, but for a shorter duration.
The logic for authorizing registration of additional credentials, and deregistration of credentials, is also in this layer. In general, anything that would be specific to a particular Relying Party (RP) would go in this layer.
This layer implements the Web Authentication Relying Party Operations, and takes care of all RP-agnostic parts of the Web Authentication logic: generating challenges and verifying all aspects of the responses. It is mostly stateless, and exposes integration points for storage of challenges and credentials. Some notable integration points are:
The library user must provide an implementation of the CredentialRepository interface to use for looking up stored public keys, user handles and signature counters.
The library user can optionally provide an instance of the
interface to enable identification and validation of authenticator models. This
instance is then used to look up trusted attestation root certificates. The
sibling library provides implementations of this interface that are pre-seeded
with Yubico device metadata.
This subproject includes two ways to run the demo server:
.war archive to be deployed in any Java web server
As a standalone Java executable
.war archive includes a simple web GUI hosted at
/, relative to the
context root of the deployed
.war application, which communicates with the
server via a REST API served at
To build it, run
$ ../gradlew war
The standalone Java executable has the main class
This server also serves the REST API at
/api/v1/, and static resources for the
To build it, run one of the following:
$ ../gradlew distTar $ ../gradlew distZip
This will build an archive which can be unpacked and run anywhere with a Java environment:
$ unzip webauthn-server-demo-$VERSION.zip $ cd webauthn-server-demo-$VERSION $ ./bin/webauthn-server-demo > ./bin/webauthn-server-demo.bat
To build and run the demo server via Gradle, run:
$ ./gradlew run
This will serve the application under
|Since WebAuthn requires a HTTPS connection, this demo server uses a dummy
certificate. This will cause your browser to show a warning, which is safe to
bypass. The dummy certificate is not included in the
Both modes of running the server accept the following environment variables for
configuration. Note that if running via Gradle, you may need to disable the
Gradle daemon (
--no-daemon) in order for the server process to have the
YUBICO_WEBAUTHN_PORT: Port number to run the server on. Example:
This is ignored when running as a `.war` artifact, since the port is controlled by the parent web server.
YUBICO_WEBAUTHN_ALLOWED_ORIGINS: Comma-separated list of origins the
server will accept requests for. Example:
YUBICO_WEBAUTHN_RP_ID: The RP ID
the server will report. Example:
YUBICO_WEBAUTHN_RP_NAME: The human-readable
the server will report. Example:
YUBICO_WEBAUTHN_RP_ICON: An optional URL to an
represent this Relying Party. Example: