docs: #2840 components (#2959)

JanssenProject · Nov 10, 2022 · fddbc51 · fddbc51
1 parent af4eda8
commit fddbc51
Show file tree

Hide file tree

Showing 8 changed files with 97 additions and 8 deletions.
diff --git a/docs/admin/fido/README.md b/docs/admin/fido/README.md
@@ -6,7 +6,87 @@ tags:
 
 # Overview
 
-Please use the left navigation menu to browse the content of this section while we are still working on developing content for `Overview` page.
+## Janssen's FIDO2 server
 
-!!! Contribute
-If you’d like to contribute to this document, get started with the [Contribution Guide](https://docs.jans.io/head/CONTRIBUTING/#contributing-to-the-documentation)
+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)](https://fidoalliance.org/metadata/metadata-service-overview/) 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.)
+
+### Components of the FIDO2 ecosystem in Janssen
+
+
+![FIDO2 ecosystem](../../assets/fido2-components.png)
+
+[Diagram reference](../../assets/fido2-components.xml)
+
+ 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 offering)
+       - manage a PIN. (capability exists but not offered in Janssen's FIDO2 offering)
+
+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.
+
+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.
+
+6. **FIDO2 Server**
+Janssen's FIDO server is a standalone server communicates with the RP using an API which can be obtained by querying the following URL :
+`https://<myjans-server>/.well-known/fido2-configuration`
+Response:
+
+    ```
+    {
+      "version": "1.1",
+      "issuer": "https://<myjans-server>",
+      "attestation": {
+        "base_path": "https://<myjans-server>/jans-fido2/restv1/attestation",
+        "options_enpoint": "https://<myjans-server>/jans-fido2/restv1/attestation/options",
+        "result_enpoint": "https://<myjans-server>/jans-fido2/restv1/attestation/result"
+      },
+      "assertion": {
+        "base_path": "https://<myjans-server>/jans-fido2/restv1/assertion",
+        "options_enpoint": "https://<myjans-server>/jans-fido2/restv1/assertion/options",
+        "result_enpoint": "https://<myjans-server>/jans-fido2/restv1/assertion/result"
+      }
+    }
+    ```
+
+    The two main functionalities are:
+    1. Attestation
+    2. Assertion
+    The authenticator credentials obtained after querying the WebAuthn API is forwarded to the FIDO2 server for attestation or assertion.
+
+7. **Interception script** : In the Janssen ecosystem, the authentication flow that comprises of the calls to WebAuthn API and the FIDO server is achieved using an interception script, details of it can be found [here](../../script-catalog/person_authentication/fido2-external-authenticator/README).
+
+
+### Attestation formats supported by Janssen's FIDO server
+* [Packed (FIDO2)](https://github.com/JanssenProject/jans/blob/main/jans-fido2/server/src/main/java/io/jans/fido2/service/processor/attestation/PackedAttestationProcessor.java): The most used attestation format
+* [TPM](https://github.com/JanssenProject/jans/blob/main/jans-fido2/server/src/main/java/io/jans/fido2/service/processor/attestation/TPMProcessor.java) : Attestation for Windows10 devices
+* [Android key attestation](https://github.com/JanssenProject/jans/blob/main/jans-fido2/server/src/main/java/io/jans/fido2/service/processor/attestation/AndroidKeyAttestationProcessor.java) : Attestation for android devices.
+* [Android SafetyNet ](https://github.com/JanssenProject/jans/blob/main/jans-fido2/server/src/main/java/io/jans/fido2/service/processor/attestation/AndroidSafetyNetAttestationProcessor.java): Any Android devices running 7+
+* [FIDO U2F](https://github.com/JanssenProject/jans/blob/main/jans-fido2/server/src/main/java/io/jans/fido2/service/processor/attestation/U2FAttestationProcessor.java): Legacy U2F authenticators
+* [Apple Anonymous](https://github.com/JanssenProject/jans/blob/main/jans-fido2/server/src/main/java/io/jans/fido2/service/processor/attestation/AppleAttestationProcessor.java): Apple devices do attestations differently.
+* [None](https://github.com/JanssenProject/jans/blob/main/jans-fido2/server/src/main/java/io/jans/fido2/service/processor/attestation/NoneAttestationProcessor.java)
+
+### Backward compatibility with U2F authenticators
+The FIDO server offers registration and authentication using legacy U2F authenticators.
+
+### References
+1. https://www.w3.org/TR/webauthn-2/
+2. http://fidoalliance.org/specs/mds/fido-metadata-statement-v3.0-ps-20210518.html
+
+### Tools
+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
diff --git a/docs/admin/fido/bluetooth-authn.md b/docs/admin/fido/bluetooth-authn.md
@@ -4,4 +4,7 @@ tags:
   - fido
 ---
 
-This page will be the landing page for the Janssen Project admin documentation
+## Troubleshooting notes:
+
+1. Enable the Bluetooth Device Permissions in Chrome Settings
+https://support.google.com/accounts/answer/9289445?hl=en&co=GENIE.Platform%3DAndroid
diff --git a/docs/admin/fido/key-mgt.md b/docs/admin/fido/key-mgt.md
@@ -4,4 +4,7 @@ tags:
   - fido
 ---
 
-This page will be the landing page for the Janssen Project admin documentation
+
+### Attestation types
+
+Basic attestation: 
diff --git a/docs/admin/fido/logs.md b/docs/admin/fido/logs.md
@@ -7,6 +7,7 @@ tags:
 ### Log level and Logging Layout Parameters of Janssen's FIDO2 server:
 
 | Field named | Example | Description|
+|--|--|--|
 |loggingLevel | "INFO" or "TRACE" or "DEBUG" | Logging level for FIDO2 server|
 |loggingLayout |"text" or "json" |Contents of logs as plain text or json format|
 

diff --git a/docs/admin/fido/platform-authn.md b/docs/admin/fido/platform-authn.md
@@ -4,4 +4,6 @@ tags:
   - fido
 ---
 
-This page will be the landing page for the Janssen Project admin documentation
+Apple Anonymous Attestation is first of its kind, providing a service like an Anonymization CA, where the authenticator works with a cloud operated CA owned by its manufacturer to dynamically generate per-credential attestation certificates such that no identification information of the authenticator will be revealed to websites in the attestation statement. Furthermore, among data relevant to the registration ceremony, only the public key of the credential along with a hash of the concatenated authenticator data and client data are sent to the CA for attestation, and the CA will not store any of these. This approach makes the whole attestation process privacy preserving. In addition, this approach avoids the security pitfall of Basic Attestation that the compromising of a single device results in revoking certificates from all devices with the same attestation certificate.
+
+https://medium.com/webauthnworks/webauthn-fido2-verifying-apple-anonymous-attestation-5eaff334c849
diff --git a/docs/admin/fido/vendor-metadata.md b/docs/admin/fido/vendor-metadata.md
@@ -229,11 +229,9 @@ Janssen's FIDO2 server -
 1.  Provides trust root certificates for verifying attestation statements during credential registrations.
 
 
-
 ### 3. Skip metadata validation
 Metadata validation is recommended but not mandatory as per FIDO2 specifications. As per the current implementation, there is no provision in the jans-fido2 server to turn this feature off. However, the intention is to implement it in the future.
 
-
 ### References:
 
 1. https://fidoalliance.org/announcing-the-new-streamlined-and-simplified-metadata-service-for-authenticator-vendors-and-customers/
diff --git a/docs/assets/fido2-components.png b/docs/assets/fido2-components.png
diff --git a/docs/assets/fido2-components.xml b/docs/assets/fido2-components.xml
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="app.diagrams.net" modified="2022-11-10T15:13:18.983Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/107.0.0.0 Safari/537.36 Edg/107.0.1418.26" etag="nYBTPMxvYjME4i8_l4Wi" version="20.5.1" type="google"><diagram id="pOTfA231V1PI72C_p3O5" name="Page-1">3Vpdd6M2EP01Pm0fnAPiw/aj7Wy66el2c5r2bPMog2yrwYiAnNj76zsCgUHIBTtgp81DjAY0wMydq5lBA2u+2f0c42j9hfkkGCDD3w2s2wFCpjVy4EdI9plk5NiZYBVTX150EDzS70QKDSndUp8klQs5YwGnUVXosTAkHq/IcByzt+plSxZU7xrhFakJHj0c1KXfqM/XmXTsGAf5Z0JX6/zOpiHPbHB+sRQka+yzt5LI+jSw5jFjPDva7OYkEMbL7ZLNuztytniwmIS8zYS7xYP7Qpe/md7Lo/F5HpGnmA9RpuUVB1v5wgPkBqBvtmSgFp6a76Up3Jcty08Mk9RRU7gAjSNw9uxwHo5W4vf3h1wVPFOmLTuRixfxcckvOEyGeAsmhEcg8SuJtbPwJoKDcJFEWi0/Mjg05jjBP7W5aTsJqlgFxWwb+kTY2IDTb2vKyWOEPXH2DUICZGu+CWBkFrPhbTjZHXWjWYADooqwDeHxHi6RE6w8MmRAoRxwbwd4ohye6xI0i4lYhsSq0H1ADRxI4JwAIvvdIDLRERDdh5zEHok4ZaFQ5MU04kdxpbgGIi4ShyHjpNk3C+w9r1Jvft3ygIZEyn0cP3+FWZQLixs3hiOfX5IVGnfjWNupOtZGdccW7FJ27Lgvv7rvJwfriF9FfCck/CFpGYWVQL+7v/1a44UmMJwUpyX3mqgb97qj5rg13YvG7Ujj3yMhhD0OXHqK3ZDVjd0UurM0ZhtfMijGNaM9kDihCSchGOWY/XzMcQImbMFDPdjQVrDnTFpib9KXFU2zGXsk9Kcig4ORF+AkoR5YI+E45nVxyX7VQNdbk/i1rK/RliVb6ZbXXBaTAHP6WlWvs5+8wwOjKZfucjVHXJWrSNgWFkQ5q5zuNSkyFEVgyBXhNUVgW7wvXRaJC5ITHtiqpKFwkGk8YKWw6Tvgo8tbLwEfAEm8/yvNA4rhk5yZDm53cmY22pdHQBQU3hzWLCncUZ7pmriWHD/JHMOV44M+MdiXBqq2tsgGI6UQaua4DCFNCcLVIsVW8iXn3EiZKIpaRkpnYLY0YO4of55CCQXupx4W63fPqVJ3S76SKtma5QppkOX2tlzVS5yZ6C2k6adShH6wvFM1pq3LOy9rTOfy5J1as0Tezink3SGz5kBqpNaMFD4Kt1p2R9xayyj75tZ6DTv/Y/qQui9mnHksqGEPYo1XYYUDugoF5kiYrrczEZHAqcFUnthQ3xfTZzEBUsaLVJWAjsyeQK8zGzi3QteWs0SCMsV0zJ7JnAWivLoNmWg7zJY0CFRRD8ygNBws5NSZwdSAzOqNGVpUpP0wg8zEzFIWlh/rM7CrcML4mpxQNLLzhUSFwX+FE/L3KKHsG1mITEm0GKcP93XMgZt/xQsS9EcLreNbfuiQygaFV8rI+5fgOsoGQ1gUxxW/DK1ucDOpaM1jPFfAlsuE9MP99VbNn/fCggEVlkKg1fgbv+K8qaw4vSFVw0mUfW9a0p3glT4Y2lJDTtMSvmjzC12hbVMhaCiVx+NKqew6J1fKRR4ImDeK5E+qc4u6/pRSvu1ycC3ytiaTGwP+FX9uFVgjdB6X2/ZEUWRp73Mpaj+3L3RODWGdVEQ0dYAqoD4d0x3mI6O26chVSxSlpW2dm42o9XHtc8vJfdLOQa3rD/UFalQBtdEA6vaoa0aTfU00KSlpsW3lZDSphTNSFPVNgLpv8deqoIybUQORFbirLsIjpzPcNbIdaonP6/a6XSURVJtzbfHpqorUxs712U7XHbzDnBOAaLYNpKHj+r+o1tAROjxUa/bEGVV8OTQ7wZqFqlqRgpD+Cjak23ByCfJqSycfJfxr33Jbh7+6EeDCn7qQrsF3B/4SoShCW/F2vRXbtl/aPtp1dX4buLyrsq8R+qhe2V+295q3aUqu+UI4FhtXBtleK6rZ3/IBmiTuuGrKYsdQyZS6vS1nfN+C4WG/bhYTh13P1qd/AA==</diagram></mxfile>