Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(jans-fido2):#2840 #2974

Merged
merged 1 commit into from
Nov 14, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 2 additions & 44 deletions docs/admin/fido/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,32 +15,6 @@ Janssen's FIDO2 server - a component inside the Janssen project enables users of
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:
Expand All @@ -62,25 +36,9 @@ Response:
}
```

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)
### Customization authentication flow using 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).

### 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/
Expand Down
2 changes: 2 additions & 0 deletions docs/admin/fido/logs.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,8 @@ Response:
B. Use the following command to update the logging level
`/opt/jans/jans-cli/config-cli.py --operation-id post-config-scripts --data /tmp/config_values.json`

C. restart `jans-fido2`
`service fido2 restart` or `systemctl restart fido2`

### Location of logs in FIDO2 server:

Expand Down
Loading