FIDO2 server implementation - maduvena/jans-docs GitHub Wiki

FIDO2 as an open standard for authentication is based on public key cryptography.

Janssen's FIDO2 server - a component inside the Janssen project enables users of RPs to enroll and authenticate themselves using U2F keys, FIDO2 keys or inbuilt platform authenticator.

1. The FIDO2 server uses REST endpoints to communicate with an RP via an https connection.
2. The FIDO2 server implements the FIDO Metadata Service (MDS3) defined by FIDO Alliance.
3. The FIDO2 server stores user data into the same persistence store as the Jans-Auth server. (LDAP, MYSQL, Couchbase etc.)

1. User: User of an application, the one who possesses the Authenticator and who's role is to pass the Test of User Presence (TUP) (touch device, look, speak etc.).

2. WebAuthn API:

   • A global web standard for password-less FIDO2 authentication, implemented by most browsers (Google Chrome, Mozilla Firefox, Microsoft Edge, Apple Safari, Opera, Microsoft edge).
   • It provides clients access to the underlying capabilities of the Authenticator.
   • WebAuthn offers a very good user experience, there is no need for any additional browser plugin to be installed.
   • WebAuthn API: enables clients to make requests to authenticators with regards to :
     • creation of a new key-pair
     • provide an assertion about a key
     • report capabilities (capability exists but not offered in Janssen's FIDO2 server)
     • manage a PIN. (capability exists but not offered in Janssen's FIDO2 server)

3. Authenticator: A device which holds the private key. It prompts the user to perform a certain gesture. It can be a platform authenticator that is built into the client device or a roaming authenticator that is connected to the client device through USB, BLE, or NFC. List of FIDO certified Authenticators

4. Relying Party: The RP (jans-auth or casa) implements a Javascript Client which makes a registration and authentication request to the WebAuthn API. The Relying Party ID is the DNS domain where the FIDO2 device will be registered and used.

5. CTAP2: Simple and lightweight hardware protocol that enables Authenticators to talk with Supported browsers.

TODO: Diagram here

Janssen's FIDO server is a standalone server communicates with the RP using an API. The API consists of 2 main functions

1. Registration
2. Authentication

An assertion is signed using the key pair for a service, which was generated during registration.

An attestation is signed using the attestation private key and attestation certificate that were burned into all models of the same device

mention the .well-known/fido2-configuration

Janssen's FIDO2 server -

1. Downloads, verifies and caches metadata BLOBs from the FIDO Metadata Service.
2. Re-downloads the metadata BLOB when it expires.
3. Provides trust root certificates for verifying attestation statements during credential registrations.

Trusted metadata entries and authenticators can be found on - https://fidoalliance.org/certification/fido-certified-products/

WebAuthn - a gobal web standard for password-less authentication, can be used by any web application running in browsers (that support WebAuthn API) like Google Chrome, Mozilla Firefox, Microsoft Edge, Apple Safari, Opera, Microsoft edge. This authentication binds users to security keys or hardware devices like phones and laptops and uses of public key cryptography thus protecting users from phishing attacks.

a. User device mints new key pair and the public key is given to the server. b. The server asks the user's device to sign data to verify the user.

1. Good user experience (passwordless login)
2. better security - usage of securitiy keys as strong, un-phishable credentials (The key tells the server which URL the user is pointed to)

• Basic
• Self
• Attestation CA (a.k.a Privacy CA)
• None
• Anonymization CA

• Packed (FIDO2): The most used attestation format
• Tpm : Attestation for Windows10 devices
• Android key attestation : Attestation for android devices.
• Android SafetyNet : Any Android devices running 7+
• FIDO U2F: Legacy U2F authenticators
• Apple Anonymous: Apple devices do attestations differently.
• None

sequenceDiagram
title Registeration flow
autonumber 1
Browser(Web Authn API)->>RP :Register user name
RP ->>Browser(Web Authn API): Challenge, RP info, username
Browser(Web Authn API)->>Security Key: Prompt Authenticator, pass username + challenge + RP info
Security Key->>User:Prompt for verification
User->>Security Key:Performs action (Test for User Presence (TUP))
Security Key->>Security Key:Create new key pair
Security Key->>Browser(Web Authn API):Response = Sign challenge, credential id + Public key
Browser(Web Authn API)->>RP:Forward response
RP ->>Browser(Web Authn API): Validated response
RP ->>FIDO2 Server: Signed response , user and Public key
FIDO2 Server->>FIDO2 Server: extract challenge and compare
FIDO2 Server->>FIDO2 Server: attestation and verification of registered device with MDS<br/> or local metadata store
FIDO2 Server->>FIDO2 Server:stores the public key
FIDO2 Server->>FIDO2 Server:persists registration info for the user
FIDO2 Server->> RP :registration success

1. 2 step login - username and password followed by use of authenticator/
2. Passwordless login

1. Use webauthn to

• report capabilities (capability not used in Janssen's FIDO2 server)
• manage a PIN. (capability not used in Janssen's FIDO2 server)

2. A similar TOC browser - parse and display - https://fidoalliance.org/certification/fido-certified-products/

3. skip attestation

1. https://www.w3.org/TR/webauthn-2/
2. http://fidoalliance.org/specs/mds/fido-metadata-statement-v3.0-ps-20210518.html

1. https://jwt.io/ – For JWT decoding and debugging
2. https://www.base64decode.org/ – For Decoding Base64 to UTF8
3. https://fidoalliance.org/certification/fido-certified-products/ - To browse authenticators listed with FIDO Alliance