-
Notifications
You must be signed in to change notification settings - Fork 144
/
README
178 lines (137 loc) · 8.31 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
= webauthn-server-demo
:idprefix:
:idseparator: -
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.
The central part is the
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/demo/webauthn/WebAuthnServer.java[`WebAuthnServer`]
class, and the
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/demo/webauthn/WebAuthnRestResource.java[`WebAuthnRestResource`]
class which provides the REST API on top of it.
== Quick start
$ ./gradlew run
$ $BROWSER https://localhost:8443/
Or to run with the https://fidoalliance.org/metadata/[FIDO Metadata Service] as
a source of attestation metadata:
$ YUBICO_WEBAUTHN_USE_FIDO_MDS=true ./gradlew run
$ $BROWSER https://localhost:8443/
== Architecture
The example webapp is made up of three main layers, the bottom of which is the
link:../webauthn-server-core/[`webauthn-server-core`]
library:
- The front end interacts with the server via a *REST API*, implemented in
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/demo/webauthn/WebAuthnRestResource.java[`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
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/demo/webauthn/WebAuthnServer.java[`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
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/2.5.4/com/yubico/webauthn/CredentialRepository.html[`CredentialRepository`]
integration point - as the
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/demo/webauthn/InMemoryRegistrationStorage.java[`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
link:../webauthn-server-core/[`webauthn-server-core`]
library gets involved. The entry point into the library is the
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/2.5.4/com/yubico/webauthn/RelyingParty.html[`RelyingParty`]
class.
+
This layer implements the Web Authentication
https://www.w3.org/TR/webauthn/#sctn-rp-operations[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
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/2.5.4/com/yubico/webauthn/CredentialRepository.html[`CredentialRepository`]
interface to use for looking up stored public keys, user handles and signature
counters.
The example app does this via the
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/demo/webauthn/InMemoryRegistrationStorage.java[`InMemoryRegistrationStorage`]
class.
** The library user can optionally provide an instance of the
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core/2.5.4/com/yubico/webauthn/attestation/AttestationTrustSource.html[`AttestationTrustSource`]
interface to enable identification and validation of authenticator models. This
instance is then used to look up trusted attestation root certificates. The
link:../webauthn-server-attestation/[`webauthn-server-attestation`]
sibling library provides an implementation of this interface that integrates
with the https://fidoalliance.org/metadata/[FIDO Metadata Service].
+
For this the example app uses the
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/com/yubico/webauthn/attestation/YubicoJsonMetadataService.java[`YubicoJsonMetadataService`]
class, which reads attestation data from a bundled JSON file. If enabled by
configuration, this is also combined with the
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-attestation/2.5.0/com/yubico/fido/metadata/FidoMetadataService.html[`FidoMetadataService`]
implementation from the
link:../webauthn-server-attestation/[`webauthn-server-attestation`] module.
== Usage
This subproject includes two ways to run the demo server:
- As a `.war` archive to be deployed in any Java web server
- As a standalone Java executable
=== `.war` archive
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
=== Standalone Java executable
The standalone Java executable has the main class
link:https://github.com/Yubico/java-webauthn-server/blob/main/webauthn-server-demo/src/main/java/demo/webauthn/EmbeddedServer.java[`demo.webauthn.EmbeddedServer`].
This server also serves the REST API at `/api/v1/`, and static resources for the
GUI under `/`.
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 `https://localhost:8443/`.
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 by the embedded Jetty server and the application distribution archives.
=== Configuration
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
correct environment.
- `YUBICO_WEBAUTHN_PORT`: Port number to run the server on. Example:
`YUBICO_WEBAUTHN_PORT=8081`
+
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 from. Example:
`YUBICO_WEBAUTHN_ALLOWED_ORIGINS=http://demo.yubico.com:8080`
- `YUBICO_WEBAUTHN_RP_ID`: The https://www.w3.org/TR/webauthn/#rp-id[RP ID]
the server will report. Example: `YUBICO_WEBAUTHN_RP_ID=demo.yubico.com`
- `YUBICO_WEBAUTHN_RP_NAME`: The human-readable
https://www.w3.org/TR/webauthn/#dom-publickeycredentialentity-name[RP name]
the server will report. Example: `YUBICO_WEBAUTHN_RP_NAME='Yubico Web Authentication demo'`
- `YUBICO_WEBAUTHN_USE_FIDO_MDS`: If set to `true` (case-insensitive), use
https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-attestation/2.5.4/com/yubico/fido/metadata/FidoMetadataService.html[`FidoMetadataService`]
from the link:../webauthn-server-attestation[`webauthn-server-attestation`]
module as a source of attestation data in addition to the static JSON file
bundled with the demo. This will write cache files to the
`webauthn-server-demo` project root directory; see the patterns in the
`.gitignore` file.