forked from Yubico/java-webauthn-server
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
159 lines (119 loc) · 7.07 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
= 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 perform auxiliary actions such as adding an additional authenticator or
deregistering a credential.
The central part is the
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-demo/src/main/java/demo/webauthn/WebAuthnServer.java[WebAuthnServer]
class, and the
https://github.com/Yubico/java-webauthn-server/blob/master/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/
```
== Architecture
The example webapp is made up of three main layers, the bottom of which is the
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-core/[`webauthn-server-core`]
library:
- The front end interacts with the server via a *REST API*, implemented in
https://github.com/Yubico/java-webauthn-server/blob/master/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
https://github.com/Yubico/java-webauthn-server/blob/master/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
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-core/src/main/java/com/yubico/webauthn/CredentialRepository.java[CredentialRepository]
integration point - as the
https://github.com/Yubico/java-webauthn-server/blob/master/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
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-core/[`webauthn-server-core`]
library gets involved. The entry point into the library is the
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-core/src/main/java/com/yubico/webauthn/RelyingParty.java[RelyingParty]
class.
+
This layer implements the Web Authentication
https://www.w3.org/TR/webauthn/#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
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-core/src/main/java/com/yubico/webauthn/CredentialRepository.java[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
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-core/src/main/java/com/yubico/webauthn/attestation/MetadataService.java[MetadataService]
interface to enable identification and validation of authenticator models. This
instance is then used to look up trusted attestation root certificates. The
https://github.com/Yubico/java-webauthn-server/blob/master/webauthn-server-attestation/[`webauthn-server-attestation`]
sibling library provides implementations of this interface that are pre-seeded
with Yubico device metadata.
== 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
https://github.com/Yubico/java-webauthn-server/blob/master/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 for. 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_ID='Yubico Web
Authentication demo'`
- `YUBICO_WEBAUTHN_RP_ICON`: An optional URL to an
https://www.w3.org/TR/webauthn/#dom-publickeycredentialentity-icon[icon] to
represent this Relying Party. Example:
`YUBICO_WEBAUTHN_RP_ICON='https://www.yubico.com/wp-content/uploads/2014/09/favicon.ico'`