Skip to content

Latest commit

 

History

History
 
 

webauthn-server-demo

README.adoc

webauthn-server-demo

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 build on API to enable advanced features like authenticated actions, such as adding an additional authenticator or deregistering a credential.

The central part is the WebAuthnServer class, and the WebAuthnRestResource class which provides the REST API on top of it.

Architecture

The example webapp is made up of three main layers, the bottom of which is the webauthn-server-core library:

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

  • The server layer in turn calls the library layer, which is where the webauthn-server-core library gets involved. The entry point into the library is the RelyingParty class.

    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 MetadataService interface to enable identification and validation of authenticator models. This instance is then used to look up trusted attestation root certificates. The webauthn-server-attestation sibling library provides implementations of this interface that are pre-seeded with Yubico device metadata.

Usage

The .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 /api/v1/.

To build it, run

$ ../gradlew war

To build and run it via Gradle, run

$ ../gradlew appRun

This will serve the application under https://localhost:8443/webauthn/ by default.

Note
 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 .war artifact; it is only used when running via Gradle.

Configuration

The server accepts 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 correct environment.

  • YUBICO_WEBAUTHN_ALLOWED_ORIGINS: Comma-separated list of origins the server will accept requests for. Example: YUBICO_WEBAUTHN_ALLOWED_ORIGINS=http://demo.yubico.com:8080

  • YUBICO_WEBAUTHN_RP_ID: The RP ID the server will report. Example: YUBICO_WEBAUTHN_RP_ID=demo.yubico.com

  • YUBICO_WEBAUTHN_RP_NAME: The human-readable RP name the server will report. Example: YUBICO_WEBAUTHN_RP_ID='Yubico Web Authentication demo'

  • YUBICO_WEBAUTHN_RP_ICON: An optional URL to an icon to represent this Relying Party. Example: YUBICO_WEBAUTHN_RP_ICON='https://www.yubico.com/wp-content/uploads/2014/09/favicon.ico'