You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Generally, the library makes the following assumptions about how a Relying Party implementing this library will
13
-
interface with a client that will handle calling the WebAuthn API:
14
-
15
-
1. JSON is the preferred data type for transmitting registration and authentication options from the server to
16
-
the client to feed to `navigator.credentials.create()` and `navigator.credentials.get()` respectively.
17
-
18
-
2. JSON is the preferred data type for transmitting WebAuthn responses from the client to the Relying Party.
19
-
20
-
3. Bytes are not directly transmittable in either direction as JSON, and so should be encoded to and decoded
21
-
using Base64 URL encoding. To make life a little bit easier ``URLEncodedBase64`` and ``EncodedBase64`` indicate whether a `String` is currently encoded or not.
12
+
> Important information in advance:
13
+
Because bytes are not directly transmittable in either direction as JSON this library provides custom `Codable` implementations for a few types.
14
+
When using `Codable` to encode ``PublicKeyCredentialCreationOptions`` and ``PublicKeyCredentialRequestOptions`` byte array properties will be encoded to base64url strings.
15
+
When using `Codable` to decode ``RegistrationCredential`` and ``AuthenticationCredential`` base64url encoded strings will be decoded to byte arrays.
16
+
When data transmission happens without JSON (e.g. through GRPC) the byte arrays can be transmitted directly. In that case don't use the default `Codable` implementation provided by this library.
22
17
23
18
## Limitations
24
19
@@ -31,21 +26,20 @@ There are a few things this library currently does **not** support:
31
26
32
27
3. Attestation verification is currently not supported, we do however plan to add support for that. Some work has been
33
28
done already, but there are more pieces missing. In most cases attestation verification is not recommended since it
34
-
causes a lot of overhead.[From Yubico](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html):
35
-
> "If a service does not have a specific need for attestation information, namely a well defined policy for what to
29
+
causes a lot of overhead.
30
+
> [From Yubico](https://developers.yubico.com/WebAuthn/WebAuthn_Developer_Guide/Attestation.html): "If a service does not have a specific need for attestation information, namely a well defined policy for what to
36
31
do with it and why, it is not recommended to verify authenticator attestations"
37
32
38
33
### Setup
39
34
40
35
Configure your backend with a ``WebAuthnManager`` instance:
41
36
42
37
```swift
43
-
app.webAuthn=WebAuthnManager(
44
-
config: WebAuthnConfig(
45
-
relyingPartyDisplayName: "My Fancy Web App",
38
+
let webAuthnManager =WebAuthnManager(
39
+
config: .init(
46
40
relyingPartyID: "example.com",
47
-
relyingPartyOrigin: "https://example.com",
48
-
timeout: 600
41
+
relyingPartyName: "My Fancy Web App",
42
+
relyingPartyOrigin: "https://example.com"
49
43
)
50
44
)
51
45
```
@@ -59,18 +53,18 @@ Scenario: A user wants to signup on a website using WebAuthn.
59
53
#### Explanation
60
54
61
55
1. When tapping the "Register" button the client sends a request to
62
-
the backend. The backend responds to this request with a call to `begingRegistration(user:)` which then returns a
56
+
the backend. The relying party responds to this request with a call to ``WebAuthnManager/beginRegistration(user:timeoutInSeconds:attestation:publicKeyCredentialParameters:)`` which then returns a
63
57
new ``PublicKeyCredentialRequestOptions``. This must be send back to the client so it can pass it to
64
58
`navigator.credentials.create()`.
65
59
66
-
2. Whatever `navigator.credentials.create()` returns will be send back to the backend, parsing it into
60
+
2. Whatever `navigator.credentials.create()` returns will be send back to the relying party, parsing it into
67
61
``RegistrationCredential``.
68
62
```swift
69
-
let registrationCredential =tryreq.content.decode(RegistrationCredential.self)
63
+
let registrationCredential =tryJSONDecoder().decode(RegistrationCredential.self)
70
64
```
71
65
72
-
3. Next the backend calls `finishRegistration(challenge:credentialCreationData:)` with the previously
73
-
generated challenge and the received ``RegistrationCredential``. If `finishRegistration` succeeds a new ``Credential``
66
+
3. Next the backend calls ``WebAuthnManager/finishRegistration(challenge:credentialCreationData:requireUserVerification:supportedPublicKeyAlgorithms:pemRootCertificatesByFormat:confirmCredentialIDNotRegisteredYet:)`` with the previously
67
+
generated challenge and the received ``RegistrationCredential``. If no error are thrown a new ``Credential``
74
68
object will be returned. This object contains information about the new credential, including an id and the generated public-key. Persist this data in e.g. a database and link the entry to the user.
75
69
76
70
##### Example implementation (using Vapor)
@@ -113,13 +107,13 @@ Scenario: A user wants to log in on a website using WebAuthn.
113
107
#### Explanation
114
108
115
109
1. When tapping the "Login" button the client sends a request to
116
-
the backend. The backend responds to this request with a call to `beginAuthentication()` which then in turn
110
+
the relying party. The relying party responds to this request with a call to ``WebAuthnManager/beginAuthentication(timeout:allowCredentials:userVerification:)`` which then in turn
117
111
returns a new ``PublicKeyCredentialRequestOptions``. This must be sent back to the client so it can pass it to
118
112
`navigator.credentials.get()`.
119
-
2. Whatever `navigator.credentials.get()` returns will be sent back to the backend, parsing it into
113
+
2. Whatever `navigator.credentials.get()` returns will be sent back to the relying party, parsing it into
120
114
``AuthenticationCredential``.
121
115
```swift
122
-
let authenticationCredential =tryreq.content.decode(AuthenticationCredential.self)
116
+
let authenticationCredential =tryJSONDecoder().decode(AuthenticationCredential.self)
0 commit comments