@@ -400,13 +400,13 @@ and credentials registered via the U2F API will continue to work with the WebAut
400
400
401
401
To migrate to using the WebAuthn API, you need to do the following:
402
402
403
- * Follow the link:#getting-started[Getting started] guide above to set up WebAuthn support in general.
403
+ 1. Follow the link:#getting-started[Getting started] guide above to set up WebAuthn support in general.
404
404
+
405
405
Note that unlike a U2F AppID, the WebAuthn link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/RelyingPartyIdentity.RelyingPartyIdentityBuilder.html#id(java.lang.String)[RP ID]
406
406
consists of only the domain name of the AppID.
407
407
WebAuthn does not support link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-appid-and-facets-v1.2-ps-20170411.html[U2F Trusted Facet Lists].
408
408
409
- * Set the
409
+ 2. Set the
410
410
link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RelyingParty.RelyingPartyBuilder.html#appId(com.yubico.webauthn.extension.appid.AppId)[`appId()`]
411
411
setting on your `RelyingParty` instance.
412
412
The argument to the `appid()` setting should be the same as you used for the `appId` argument to the
@@ -416,36 +416,36 @@ This will enable the link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sc
416
416
and link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sctn-appid-exclude-extension[`appidExclude`]
417
417
extensions and configure the `RelyingParty` to accept the given AppId when verifying authenticator signatures.
418
418
419
- * Generate a link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#user-handle[user handle] for each existing user
420
- and store it in their account,
421
- or decide on a method for deriving one deterministically from existing user attributes.
422
- For example, if your user records are assigned UUIDs, you can use that UUID as the user handle.
423
- You SHOULD NOT use a plain username or e-mail address, or hash of either, as the user handle -
424
- for more on this, see the link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sctn-user-handle-privacy[User Handle Contents]
425
- privacy consideration.
426
-
427
- * When your `CredentialRepository` creates a `RegisteredCredential` for a U2F credential,
428
- use the U2F key handle as the
429
- link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#credentialId(com.yubico.webauthn.data.ByteArray)[credential ID].
430
- If you store key handles base64 encoded, you should decode them using
431
- link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/ByteArray.html#fromBase64(java.lang.String)[`ByteArray.fromBase64`]
432
- or
433
- link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/ByteArray.html#fromBase64Url(java.lang.String)[`ByteArray.fromBase64Url`]
434
- as appropriate before passing them to the `RegisteredCredential`.
435
-
436
- * When your `CredentialRepository` creates a `RegisteredCredential` for a U2F credential,
437
- use the
438
- link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#publicKeyEs256Raw(com.yubico.webauthn.data.ByteArray)[`publicKeyEs256Raw()`]
439
- method instead of link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#publicKeyCose(com.yubico.webauthn.data.ByteArray)[`publicKeyCose()`]
440
- to set the credential public key.
441
-
442
- * Replace calls to the U2F
443
- link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html#high-level-javascript-api[`register`]
444
- method with calls to `navigator.credentials.create()` as described in link:#getting-started[Getting started].
445
-
446
- * Replace calls to the U2F
447
- link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html#high-level-javascript-api[`sign`]
448
- method with calls to `navigator.credentials.get()` as described in link:#getting-started[Getting started].
419
+ 3. Generate a link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#user-handle[user handle]
420
+ for each existing user and store it in their account,
421
+ or decide on a method for deriving one deterministically from existing user attributes.
422
+ For example, if your user records are assigned UUIDs, you can use that UUID as the user handle.
423
+ You SHOULD NOT use a plain username or e-mail address, or hash of either, as the user handle -
424
+ for more on this, see the link:https://www.w3.org/TR/2021/REC-webauthn-2-20210408/#sctn-user-handle-privacy[User Handle Contents]
425
+ privacy consideration.
426
+
427
+ 4. When your `CredentialRepository` creates a `RegisteredCredential` for a U2F credential,
428
+ use the U2F key handle as the
429
+ link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#credentialId(com.yubico.webauthn.data.ByteArray)[credential ID].
430
+ If you store key handles base64 encoded, you should decode them using
431
+ link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/ByteArray.html#fromBase64(java.lang.String)[`ByteArray.fromBase64`]
432
+ or
433
+ link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/data/ByteArray.html#fromBase64Url(java.lang.String)[`ByteArray.fromBase64Url`]
434
+ as appropriate before passing them to the `RegisteredCredential`.
435
+
436
+ 5. When your `CredentialRepository` creates a `RegisteredCredential` for a U2F credential,
437
+ use the
438
+ link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#publicKeyEs256Raw(com.yubico.webauthn.data.ByteArray)[`publicKeyEs256Raw()`]
439
+ method instead of link:https://developers.yubico.com/java-webauthn-server/JavaDoc/webauthn-server-core-minimal/latest/com/yubico/webauthn/RegisteredCredential.RegisteredCredentialBuilder.html#publicKeyCose(com.yubico.webauthn.data.ByteArray)[`publicKeyCose()`]
440
+ to set the credential public key.
441
+
442
+ 6. Replace calls to the U2F
443
+ link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html#high-level-javascript-api[`register`]
444
+ method with calls to `navigator.credentials.create()` as described in link:#getting-started[Getting started].
445
+
446
+ 7. Replace calls to the U2F
447
+ link:https://fidoalliance.org/specs/fido-u2f-v1.2-ps-20170411/fido-u2f-javascript-api-v1.2-ps-20170411.html#high-level-javascript-api[`sign`]
448
+ method with calls to `navigator.credentials.get()` as described in link:#getting-started[Getting started].
449
449
450
450
Existing U2F credentials should now work with the WebAuthn API.
451
451
0 commit comments