A tutorial for developers on how to implement passwordless authentication for web apps utilizing FIDO security keys.

1. 1
©2019Yubico
© 2019 Yubico
Securing a Web App with
Passwordless Web Authentication
Add WebAuthn to an existing web app

2. 2
©2019Yubico
● Workshop Overview
○ What is passwordless authentication
○ Security Key as the Root of Trust
○ What to expect and what you’ll need to get started
● Overview of Yubico’s java-webauthn-server architecture
○ Credential repository
○ Registering credentials
○ Authenticating credentials
● Best practices
● Start coding!
Agenda

3. 3
©2019Yubico
● Strong MFA
○ WebAuthn offers a strong Multi-Factor Authentication framework to
minimize or replace the use of passwords with scoped public key-based
credentials that are resistant to phishing, replay, and server breach attacks.
● Passwordless Auth enabled by
○ W3C Webauthn + FIDO2 Client to Authenticator Protocol version 2.0
(CTAP2) specs and resident credentials.
● Resident Credentials
○ Authenticator not only store the private key but also a user handle. The
server can associate the user handle with an identity for authentication.
What is Passwordless Authentication with WebAuthn?

4. 4
©2019Yubico
Security Keys as Root of Trust
Anchoring FIDO2 / WebAuthn credentials in a root of trust is the
cornerstone for building a secure identity model
● A hardware-backed root of trust strengthens the account lifecycle
○ Authentication, Step-Up Authentication, Account Recovery, Bootstrapping New
Devices
● An external authenticator, as the root of trust, is the anchor that
creates a chain of trust with the internal authenticator
○ Recording the authenticator used to register other authenticators creates a chain of
trust that can be audited at a later date

5. 5
©2019Yubico
Passwordless Migration Strategy
4. Eliminate
Passwords
3. Transition users to
passwordless deployment
2. Minimize use of passwords in user
flows
1. Deploy the WebAuthn / FIDO2 credential
management system across the account lifecycle

6. 6
©2019Yubico
Learn how to implement passwordless authentication for web apps
using:
● Yubico WebAuthn Server Libraries
● Spring Framework
● Client to Authenticator Protocol Version 2.0 Compatible Browser
○ Resident Credentials
● FIDO2 Security Key
What to expect from this workshop

7. 7
©2019Yubico
Some knowledge of:
● Java
● Spring Framework
● JavaScript
● WebAuthn API
○ Browser with resident credential capability
● Security Keys
○ YubiKey Manager to reset FIDO credentials after workshop
You need

8. 8
©2019Yubico
This workshop is split into multiple modules. Each module builds
upon the previous module as you expand the application. You must
complete each module before proceeding to the next.
1. Getting Started Instructions
2. Implement a Credential Repository
3. Implement WebAuthn Registration REST Endpoints
4. Implement WebAuthn Authentication REST Endpoints
5. Clean Up Instructions
Workshop Modules

9. 9
©2019Yubico
This workshop can either be completed locally or in the cloud.
● Instructions for running in the Azure Cloud Shell are included. If you already have a
subscription you can use it or you can get a free trial. Azure Cloud Shell has all of the
prerequisites already installed.
● If you prefer a different cloud development environment, feel free to use it instead.
Prerequisites:
● Git
● JDK 1.8+
● Maven 3.2+
● FIDO2 compatible platform / browser
○ MacOS: Safari Technology Preview version 71+
○ Windows 10 version 1809+ with Edge
● Your preferred text editor or IDE
● A security key
Development Environment

10. 10
©2019Yubico
● Enable the Develop Menu
○ Choose Safari > Preferences, and click Advanced.
○ At the bottom of the pane, select the “Show Develop menu in menu bar”
checkbox.
● Enable Web Authentication Experimental Feature
○ Choose Safari > Develop > Experimental Features
○ Verify “Web Authentication” is checked
● Private Window
○ Running a web app on https://localhost:8443 may require using new private
window
● No Security Key PIN Support
○ Security keys with a PIN set may not work with Safari yet.
○ You can reset a security key back to factory default settings with the
YubiKey Manager. Warning: A reset will remove all FIDO credentials.
macOS Safari TP Tips

11. 11
©2019Yubico
Start by cloning the repository
● git clone https://github.com/elukewalker/PasswordlessWorkshop
Getting Started

12. 12
©2019Yubico
WebAuthn Application Architecture
WebAuthn
API in
Browser
Client/Platform
CTAP1
and/or
CTAP2
Server-Side
App
Relying Party
WebAuthn
Server
WebAuthn
Platform
Auth API
Internal
Authenticator
External
Authenticator
User
Store
External
Metadata
Services
Register
and
Authenticate
Client-Side
JS
Attestation
Trust Store

13. 13
©2019Yubico
WebAuthn Demo Server Data Flow
Browser API Server
app logic
Core librarystartRegistration()
startAuthentication()
PublicKeyCredentialCreationOptions
PublicKeyCredentialRequestOptions
Client side JS
Encode
to JSON
Decode
JSON
navigator.credentials
.create()
.get()
Encode
to JSON
Decode
JSON
finishRegistration()
finishAssertion()
UserIdentity
PublicKeyCredential
RegistrationResult
AssertionResult
Generate
challenge
etc.
Handle
result
Inform
user
Validation
logic

14. 14
©2019Yubico
Yubico/java-webauthn-server
webauthn-server-core/
● Entity Data Model
○ Assertion Request
○ Assertion Result
○ Attestation Object
○ Authenticator Response
○ Public Key Credential
○ Public Key Credential Creation
and Request Options
○ Registration Result
○ User Identity
○ Attestation
● Data Providers
○ Credential Repository
○ Metadata Service
● Methods
○ Registration
○ Authentication
○ Authenticated Actions

15. 15
©2019Yubico
WebAuthn Demo Server Architecture
REST API
HTTP/JSON translation
Entities
Registration
Authentication
Registration storage
Persistent state
Entry Points WebAuthn-Server-Core Data Providers
DB
Server layer
Transient state
(stateless)
Metadata lookup DB
External
servicesConfiguration
Constructor parameters
Not included in workshop

16. 16
©2019Yubico
Application logic
Core Library internal structure
DB
DB
External
services
Constructor parameters
Start
operation
UserIdentity
PKCCreationOptions
PKCRequestOptions
Registration
storage
Metadata
source
Operation
settings
Challenge
generator
Finish
operation
Class RelyingParty
PublicKeyCredential
RegistrationResult
AssertionResult

17. 17
©2019Yubico
What you need to provide
● Storage for requests (temporary)
○ Completely external to the library
○ Library simply returns request objects
○ finish* methods expect them to be passed back in
● Storage for credentials (persistent)
○ Library requires an adapter object (CredentialRepository)
○ Library only looks credentials up
○ You need to save new registrations to the DB
● (Optional) Additional authenticator metadata sources
○ In the future, the library will include a FIDO Metadata Service connector
○ Optional module with Yubico device metadata as static files

18. 18
©2018Yubico
© 2018 Yubico
Registration Walkthrough

19. 19
©2019Yubico
rp: relying party data. name is required. If id is left out then origins effective
domain is used
user: identity data. name, displayName (user friendly), and id
(userHandle) are required
challenge: contains challenge for generating the newly created credential’s
attestationObject
pubKeyCredParams: desired properties of credential to be created. type:
only one type: “public-key”. alg: crypto signature algorithm preference
excludeCredentials: limits creation of multiple creds for same account on
a single authenticator. Credential descriptor includes cred type and cred id
authenticatorSelection: specify authenticator requirements. When the
requireResidentKey is true the authenticator must create a client side
resident private key. userVerification can be “preferred”, “required”, or
“discouraged”
attestation: attestation conveyance preference. Default is “none”. “direct”
indicates the rp wants to receive the attestation statement. “indirect”
indicates prefers an attestation statement
Public Key Credential Creation Options

20. 20
©2019Yubico
Registration Sequence
hash(rpId), id, kpub
, s, Apub
id, clientData,
attestationObject
Verify origin
Verify challenge
Check Apub
trust
Check s using Apub
Register kpub
, id and
userHandle
Generate key
pair (kpriv
, kpub
)
for rpId and
sign c and kpub
after User
Presence/
Verification
hash(challenge, origin)
clientData
signature(hash(rpId) || id || kpub
|| c, Apriv
)
Validate rpId
against originrpId, c, userHandle
Client Relying PartyAuthenticator
attestationObject
rpId, userHandle, challenge

21. 21
©2019Yubico
Start Registration Diagram
username,
displayName,
credNickname
REST API Start
Registration
Challenge
Generator
Registration
Request
challenge
username,
credNickname
User Identity
username,
displayName
Exclude
Credentials
Extensions
RelyingParty
Start
Registration
PublicKeyCredentialCreationOptions
Register
Request
Storage
return
RegistrationRequest
to client as JSON
Credential
Repository

22. 22
©2019Yubico
Credential Create Response
“authData”:... “fmt”:“packed” “attStmt”:...
attestationObject
RP ID Hash Flags Counter Att. Cred Data Extensions
AAGUID L Cred. ID Cred Public Key
Authenticator Data
“alg”: ... “sig”: ... “x5c”: ...
Attestation Statement
“alg”: ... “sig”: ... “ecdaaKeyId”: ...
If Basic or Privacy CA
If ECDAA
Refer to W3C Web Authentication API for more
details on attestation statements
ED AT: 1 UV UP: 1

23. 23
©2019Yubico
Finish Registration Diagram
JSON
response
REST API
Finish
Registration
Credential
Registration
Registration
Response
Register
Request
Storage
Registration
Request
Caller Token
Binding Id
RelyingParty
Finish
Registration
Credential
Repository
addRegistration
Registration
Result
Successful
Registration
Result
Performs registration
validation steps
Returned to client
Get by id
and
invalidate

24. 24
©2019Yubico
Registration Recap
1. Client calls startRegistration() endpoint
○ With userName, displayName, and credentialNickname args
2. Relying Party generates RegistrationRequest
○ With userName, credentialNickname, and PublicKeyCredentialCreationOptions
3. Client calls navigator.credentials.create()
○ With data from the RegistrationRequest
4. Client calls finishRegistration() endpoint
○ With authenticatorAttestationResponse JSONObject
5. Relying Party verifies attestation signature
○ After validation, add user and associated credential to the credential repository

25. 25
©2018Yubico
© 2018 Yubico
Authentication Walkthrough

26. 26
©2019Yubico
challenge: contains challenge that the authenticator signs as part of the
authentication assertion
rpId: relying party identifier claimed by the caller
allowCredentials: list of public key credentials acceptable to the caller, can
be omitted for username-less authentication. type: only one type:
“public-key”. id: credential Id of the public key credentials
userVerification: the default is “preferred”. Can also be set to “required” or
“discouraged”
Public Key Credential Request Options

27. ©2018Yubico
Authentication Sequence
First factor mode
Client Relying Party
id, rpId, challenge
id, hash(rpId), s, clientData,
userHandle
Find user with id or
userHandle
Check id
Check s using kpub
Verify origin
Verify challenge
Authenticator
signature(hash(rpId) || c, kpriv
)
Validate rpId
against origin
hash(challenge, origin)
clientData
id, rpId, c
Retrieve kpriv
for rpId
Sign c after User
Presence/
Verification
id, hash(rpId), s, userHandle

28. 28
©2019Yubico
Start Authentication Diagram
username
REST API Start
Authentication
Challenge
Generator
Assertion
Request
challenge
username
RelyingParty
Start
Assertion
Credential
Repository
username
Extensions
PublicKeyCredentialRequestOptions
Assertion
Request
Storage
return
AssertionRequest to
client as JSON
Get
credentials
by username

29. 29
©2019Yubico
Client - Get Credential Response
“authData”: ... “clientDataJSON”: ... “signature”: ...
Authenticator Assertion Response
RP ID Hash Flags Counter Extensions
Authenticator Data
ED AT: 0 UV UP: 1
“userHandle”: ...

30. 30
©2019Yubico
Finish Authentication Diagram
JSON
response
REST API Finish
Authentication
Successful
Authentication
Result
Assertion
Response
Assertion
Request
Caller Token
Binding Id
RelyingParty
Finish
Assertion
Credential
RepositoryUpdate
signature
count
Assertion
Result
Performs authentication
validation steps
Returned to
client
Get by id
and
invalidate
Assertion
Request
Storage
Credential
Repository
Get credentials by
userHandle

31. 31
©2019Yubico
Authentication Recap
1. Client calls startAuthentication() endpoint
○ With (or without) userName
2. Relying Party generates AssertionRequest
○ With userName, and PublicKeyCredentialRequestOptions
3. Client calls navigator.credentials.get()
○ With data from the AssertionRequest
4. Client calls finishAuthentication() endpoint
○ With authenticatorAssertionResponse JSONObject
5. Relying Party verifies signature
○ After validation, authentication is successful

32. 32
©2019Yubico
Best Practices
● Store the verbatim attestation object
○ Enables future re-evaluation of trust
● Allow registering more than one credential per account
○ Consider allowing credential nicknames
● Weigh pros vs cons of requiring attestation
○ Pros:
‒ Higher assurance
○ Cons:
‒ Maintenance for attestation trust store
‒ Compatibility issues for unknown/new authenticators (not in attestation trust
store)
● Security and Privacy Considerations
○ Refer to W3C Web Authentication API spec
https://www.w3.org/TR/webauthn/#security-considerations

33. 33
©2019Yubico
Recap
● Anchoring resident credentials on roaming authenticators can
enable passwordless authentication scenarios
● Yubico’s java-webauthn-core library provides the entities and
validation logic to integrate Web Authentication into server-side
applications
● Attestation can be stored and looked up to build a chain of trust
and provide high assurance authentication
● Build a UI that enables users to register multiple authenticators

34. 34
©2019Yubico
Resources
● Workshop
○ https://github.com/elukewalker/PasswordlessWorkshop
● FIDO2/WebAuthn Developer Guide
○ https://developers.yubico.com/FIDO2/FIDO2_WebAuthn_Developer_Guide/
● Java WebAuthn Server
○ https://github.com/Yubico/java-webauthn-server
● Yubico Developer Videos
○ https://www.yubico.com/why-yubico/for-developers/developer-videos/
● W3C Web Authentication API
○ https://www.w3.org/TR/webauthn
● FIDO Client to Authenticator Protocol V 2.0
○ https://fidoalliance.org/specifications/download/

35. 35
©2019Yubico
yubi.co/devs
Workshops, Webinars, Documentation,
Implementation Guides, Reference Code,
APIs, SDKs
Yubico Developer Program

36. 36
©2019Yubico
Raise your hand if you need help
Workshop repository
https://github.com/elukewalker/PasswordlessWorkshop
Questions?

37. 37
©2019Yubico
© 2019 Yubico