From d3351e141fa546074ad98891e655247a0c23e30a Mon Sep 17 00:00:00 2001 From: Madhumita Subramaniam Date: Mon, 14 Nov 2022 16:44:19 +0530 Subject: [PATCH] fix(jans-fido2):#2840 (#2974) --- docs/admin/fido/README.md | 46 +--- docs/admin/fido/logs.md | 2 + docs/admin/reference/database/mysql-schema.md | 216 +++++++++--------- docs/admin/reference/json/fido.md | 50 +++- .../implementation-design/jans-fido2.md | 93 +++++++- 5 files changed, 253 insertions(+), 154 deletions(-) diff --git a/docs/admin/fido/README.md b/docs/admin/fido/README.md index 7074c926a4c..a01a38cc087 100644 --- a/docs/admin/fido/README.md +++ b/docs/admin/fido/README.md @@ -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:///.well-known/fido2-configuration` Response: @@ -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/ diff --git a/docs/admin/fido/logs.md b/docs/admin/fido/logs.md index e6ba4e54b2d..645cd1c062d 100644 --- a/docs/admin/fido/logs.md +++ b/docs/admin/fido/logs.md @@ -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: diff --git a/docs/admin/reference/database/mysql-schema.md b/docs/admin/reference/database/mysql-schema.md index a90fd6234c7..02d146768e6 100644 --- a/docs/admin/reference/database/mysql-schema.md +++ b/docs/admin/reference/database/mysql-schema.md @@ -8,7 +8,7 @@ tags: ```mermaid erDiagram - jansConfiguration { + jansAppConf { string doc_id PK "" string ou "casa,jans-conf-api,jans-scim, jans-fido2" string jansConfDyn "json configuration for the app" @@ -18,21 +18,21 @@ erDiagram string doc_id PK "eg - username1 username2" string dn "eg: inum=username1,ou=person,o=jans" string displayName - string inum + string inum string memberOf FK "JSON array of dn from jansGrp" string mail string uid string userPassword string jansAdminUIRole FK "...." } -jansPerson ||--o{ jansGrp: belongs-to -jansGrp ||--o{ jansPerson : contains - +jansPerson ||--o{ jansGrp: belongs-to +jansGrp ||--o{ jansPerson : contains + jansGrp { string doc_id PK "60B7" string dn "inum=60B7,ou=groups,o=jans" string displayName - string member FK "json array of dn from jansPerson" + string member FK "json array of dn from jansPerson" string inum "inum=60B7" string owner FK "dn from jansPerson" @@ -40,54 +40,54 @@ jansGrp { jansCustomScr { string doc_id PK "eg : 031C-4A65" - string dn "inum=031C-4A65, ou=script,o=jans" + string dn "inum=031C-4A65, ou=script,o=jans" string inum "same as doc_id" string displayName string jansScr "the entire script content" string jansScrType "person_authentication,update_token" - boolean jansEnabled "0/1" + boolean jansEnabled "0/1" } jansScr { - string doc_id PK - string dn - string inum + string doc_id PK + string dn + string inum string jansScr string jansScrTyp } jansFido2AuthnEntry { string doc_id PK - string dn - string jansId - datetime creationDate - string jansSessStateId - string jansCodeChallenge + string dn + string jansId + datetime creationDate + string jansSessStateId + string jansCodeChallenge string personInum FK "inum from jansPerson" - string jansAuthData - string jansStatus - string jansCodeChallengeHash + string jansAuthData + string jansStatus + string jansCodeChallengeHash } -jansPerson ||--o{ jansFido2AuthnEntry : contains +jansPerson ||--o{ jansFido2AuthnEntry : contains jansFido2RegistrationEntry { - string doc_id PK - string dn - string jansId - datetime creationDate - string displayName - string jansSessStateId - string jansCodeChallenge - string jansCodeChallengeHash - string jansPublicKeyId + string doc_id PK + string dn + string jansId + datetime creationDate + string displayName + string jansSessStateId + string jansCodeChallenge + string jansCodeChallengeHash + string jansPublicKeyId string personInum FK "inum from jansPerson" - string jansRegistrationData - string jansDeviceNotificationConf - string jansCounter + string jansRegistrationData + string jansDeviceNotificationConf + string jansCounter string jansStatus } -jansPerson ||--o{ jansFido2RegistrationEntry : contains +jansPerson ||--o{ jansFido2RegistrationEntry : contains -jansClnt { +jansClnt { string doc_id PK "fd46d193-bca6-4343-b49f-6e0b020197c3" string dn "inum=fd46d193-bca6-4343-b49f-6e0b020197c3,ou=clients,o=jans" string displayName "some name" @@ -95,10 +95,10 @@ jansClnt { string jansScope FK "json array containing inum values from jansScope" string jansClaim FK "json array containing inum from jansAttr" } -jansClnt ||--o{ jansScope : contains -jansClnt ||--o{ jansSectorIdentifier : contains +jansClnt ||--o{ jansScope : contains +jansClnt ||--o{ jansSectorIdentifier : contains -jansClnt ||--o{ jansAttr : contains +jansClnt ||--o{ jansAttr : contains jansClntAuthz ||--|{ jansClnt : linked-with jansClntAuthz ||--|{ jansPerson : linked-with @@ -122,13 +122,13 @@ jansScope{ string jansScopeTyp "openid, oauth" string jansClaim FK "JSON array of 0 or more inums from jansAttr" } -jansScope ||--o{ jansAttr : mapped-to +jansScope ||--o{ jansAttr : mapped-to jansAttr{ string doc_id PK "11AA" - string dn "inum=11AA,ou=attributes,o=jans" + string dn "inum=11AA,ou=attributes,o=jans" string displayName - string jansAttrName + string jansAttrName string inum "same as doc_id" } @@ -142,162 +142,162 @@ jansSectorIdentifier{ } jansCibaReq{ - string doc_id PK - string dn - string authReqId FK "" - string clnId FK "" - + string doc_id PK + string dn + string authReqId FK "" + string clnId FK "" + string usrId FK "doc_id from jansPerson" - datetime creationDate - datetime exp - string jansStatus "active or inactive" + datetime creationDate + datetime exp + string jansStatus "active or inactive" } jansToken ||--o{ jansClnt : mapped-to jansToken{ - string doc_id PK - string dn + string doc_id PK + string dn string usrId FK "doc_id from jansPerson" string ssnId FK "" - string uuid + string uuid string tknCde string clnId FK "JSOn array containing dn of jansClnt" } jansUmaPCT { - string doc_id PK + string doc_id PK string dn string clnId FK "json array of multiple inums from jansClnt" - string iat + string iat string tknCde FK "" string ssnId FK string jansClaimValues FK "" - string dpop + string dpop string authzCode string grtId FK "... from jansGrant" - string grtTyp + string grtTyp string jwtReq - string nnc + string nnc string scp FK "" string tknTyp string usrId FK "doc_id from jansPerson" string jansUsrDN FK "dn from jansPerson" strin acr string uuid - string chlng - string chlngMth - string clms - string attr FK "" + string chlng + string chlngMth + string clms + string attr FK "" string tknBndCnf - + } jansUmaRPT { string doc_id PK - string dn + string dn string clnId FK "" string tknCde FK "" string usrId FK "doc_id from jansPerson" string ssnId FK "" string jansUmaPermission FK "" - string uuid - string dpop + string uuid + string dpop string authzCode string grtId FK "" - string grtTyp FK "" - string jwtReq - string nnc - string scp FK "" + string grtTyp FK "" + string jwtReq + string nnc + string scp FK "" string tknTyp string jansUsrDN FK "doc_id from jansPerson" - string acr + string acr string chlng - string chlngMth + string chlngMth string clms FK "" string attr FK "" - string tknBndCnf + string tknBndCnf } jansUmaResource { string doc_id PK - string objectClass - string dn + string objectClass + string dn string displayName - string inum + string inum string owner FK "" string jansAssociatedClnt FK "" string jansUmaScope FK "" - string jansFaviconImage + string jansFaviconImage string jansGrp FK "" - string jansId - string jansResource - string jansRevision - string jansTyp - string jansScopeExpression - string description + string jansId + string jansResource + string jansRevision + string jansTyp + string jansScopeExpression + string description } jansUmaResourcePermission { string doc_id PK - string dn + string dn string exp string del - string jansUmaScope - string jansConfCode - string jansResourceSetId + string jansUmaScope + string jansConfCode + string jansResourceSetId string jansAttrs string jansTicket - string jansStatus - + string jansStatus + } jansGrant { - string doc_id PK - string dn - string grtId + string doc_id PK + string dn + string grtId } jansPerson ||--o{ jansSessId : has jansSessId ||--|{ jansClnt : associated-with jansSessId { - string doc_id PK - string objectClass - string dn + string doc_id PK + string objectClass + string dn string jansId string sid string creationDate string jansUsrDN FK "dn from jansPerson" string authnTime - string jansState + string jansState string jansSessState string jansPermissionGranted - string jansAsJwt - string jansJwt - string jansPermissionGrantedMap + string jansAsJwt + string jansJwt + string jansPermissionGrantedMap string jansInvolvedClnts FK "" - string jansSessAttr + string jansSessAttr } jansClnt ||--o{ jansSectorIdentifer : contains -jansPairwiseIdentifier }o--|| jansPerson : linked-with +jansPairwiseIdentifier }o--|| jansPerson : linked-with jansSectorIdentifer { - string doc_id PK - string objectClass - string dn - string jansId - string description - string jansRedirectURI - string jansClntId FK "json array of multiple inums from jansClnt" + string doc_id PK + string objectClass + string dn + string jansId + string description + string jansRedirectURI + string jansClntId FK "json array of multiple inums from jansClnt" } jansPairwiseIdentifier{ string doc_id PK string objectClass - string dn - string jansId + string dn + string jansId string jansSectorIdentifier FK "" string jansClntId FK "json array of multiple inums from jansClnt" string jansUsrId FK "doc_id from jansPerson" diff --git a/docs/admin/reference/json/fido.md b/docs/admin/reference/json/fido.md index a81a4bed825..200da557084 100644 --- a/docs/admin/reference/json/fido.md +++ b/docs/admin/reference/json/fido.md @@ -5,5 +5,53 @@ tags: - json --- -This is a placeholder +Use the following command to obtain configuration parameters: +`/opt/jans/jans-cli/config-cli.py --operation-id get-properties-fido2` + +Response: +``` +{ + "issuer":"https://.jans.io", + "baseEndpoint":"https://my-jans-server.jans.io/jans-fido2/restv1", + "cleanServiceInterval":60, + "cleanServiceBatchChunkSize":10000, + "useLocalCache":true, + "disableJdkLogger":true, + "loggingLevel":"INFO", + "loggingLayout":"text", + "externalLoggerConfiguration":"", + "metricReporterInterval":300, + "metricReporterKeepDataDays":15, + "metricReporterEnabled":true, + "personCustomObjectClassList":[ + "jansCustomPerson", + "jansPerson" + ], + "fido2Configuration":{ + "authenticatorCertsFolder":"/etc/jans/conf/fido2/authenticator_cert", + "mdsCertsFolder":"/etc/jans/conf/fido2/mds/cert", + "mdsTocsFolder":"/etc/jans/conf/fido2/mds/toc", + "serverMetadataFolder":"/etc/jans/conf/fido2/server_metadata", + "requestedCredentialTypes":[ + "RS256", + "ES256" + ], + "requestedParties":[ + { + "name":"https://my-jans-server.jans.io", + "domains":[ + "my-jans-server.jans.io" + ] + } + ], + "userAutoEnrollment":false, + "unfinishedRequestExpiration":180, + "authenticationHistoryExpiration":1296000 + } +} + +``` +### References: + +1. [Configuring the FIDO2 server](../../fido/config) diff --git a/docs/developer/implementation-design/jans-fido2.md b/docs/developer/implementation-design/jans-fido2.md index 2cc30f714e7..92cb0495008 100644 --- a/docs/developer/implementation-design/jans-fido2.md +++ b/docs/developer/implementation-design/jans-fido2.md @@ -1 +1,92 @@ -This file is a placeholder. +--- +tags: + - developer + - fido +--- + +# Overview + +## Janssen's FIDO2 server + +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:///.well-known/fido2-configuration` +Response: + + ``` + { + "version": "1.1", + "issuer": "https://", + "attestation": { + "base_path": "https:///jans-fido2/restv1/attestation", + "options_enpoint": "https:///jans-fido2/restv1/attestation/options", + "result_enpoint": "https:///jans-fido2/restv1/attestation/result" + }, + "assertion": { + "base_path": "https:///jans-fido2/restv1/assertion", + "options_enpoint": "https:///jans-fido2/restv1/assertion/options", + "result_enpoint": "https:///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