diff --git a/docs/admin/fido/config.md b/docs/admin/fido/config.md index 263c941ff16..43998ca53f9 100644 --- a/docs/admin/fido/config.md +++ b/docs/admin/fido/config.md @@ -1,7 +1,119 @@ --- tags: - administration - - fido + - fido2 + --- -This page will be the landing page for the Janssen Project admin documentation +### Configuration Parameters of Janssen's FIDO2 server: +| Field named | Example | Description| +|--|--|--| +|issuer| https://my-jans-server.jans.io | URL using the https scheme with no query or fragment component. The OP asserts this as its Issuer Identifier| + |baseEndpoint| https://my-jans-server/jans-fido2/restv1 | Base URL of the FIDO2 server Endpoints | + | cleanServiceInterval | 60| Time interval for the Clean Service in seconds. | + |cleanServiceBatchChunkSize | 10000| Each clean up iteration fetches chunk of expired data per base dn and removes it from storage. | + | useLocalCache | true| Boolean value specifying whether to enable local in-memory cache for attributes, scopes, clients and organization configuration| + | disableJdkLogger |true| Boolean value specifying whether to enable JDK Loggers | + |loggingLevel | "INFO" or "TRACE" or "DEBUG" | Logging level for FIDO2 server| + |loggingLayout |"text" or "json"|Contents of logs as plain text or json format| + |externalLoggerConfiguration||Path to external log4j2 logging configuration| + |metricReporterInterval|300|The interval for metric reporter in seconds.| + |metricReporterKeepDataDays|15|The number of days to retain metric reported data in the system| + |metricReporterEnabled| true |Boolean value specifying whether to enable Metric Reporter| + | personCustomObjectClassList | ["jansCustomPerson", "jansPerson" ] |LDAP custom object class list for dynamic person enrollment.| + |fido2Configuration|See JSON contents in the below example | FIDO2 Configuration | +| authenticatorCertsFolder | /etc/jans/conf/fido2/authenticator_cert |Authenticators certificates fodler. | +| mdsCertsFolder | /etc/jans/conf/fido2/mds/cert |MDS TOC root certificates folder. | +| mdsTocsFolder | /etc/jans/conf/fido2/mds/toc |MDS TOC files folder. | +| serverMetadataFolder | /etc/jans/conf/fido2/server_metadata | Authenticators metadata in json format. Example: virtual devices.| +|requestedCredentialTypes|["RS256","ES256"]| | +| requestedParties| [{"name":"https://my-jans-server.jans.io","domains":["my-jans-server.jans.io"]}]| Requested party name.| + |userAutoEnrollment |false|Allow to enroll users on enrollment/authentication requests.| + |unfinishedRequestExpiration| 180|Expiration time in seconds for pending enrollment/authentication requests| + |authenticationHistoryExpiration|1296000|Expiration time in seconds for approved authentication requests.| + +### Configuring the FIDO2 server: +#### 1. Read Configuration parameters: + +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 + } +} + +``` + + +#### 2. Update configuration parameters: + Steps: + A. Create a JSON file say `/tmp/config_values.json` by editing the JSON from Point 1 + B. Use the following command + `/opt/jans/jans-cli/config-cli.py --operation-id post-config-scripts --data /tmp/config_values.json` + +#### 3. Change log level of FIDO2 server + Steps: + A. Create a JSON file say `/tmp/config_values.json` by editing the JSON from Point 1. Edit `loggingLevel` to `TRACE` or `DEBUG` or `INFO` + B. Use the following command + `/opt/jans/jans-cli/config-cli.py --operation-id put-properties-fido --data /tmp/config_values.json` + +#### 4. Locating FIDO2 configuration in Persistence Layer + +While it is not recommended that an administrator directly edits a configuration at the persistence layer, it may be useful information for a developer. + +##### A. MySQL +```mermaid +erDiagram + jansAppConf { + string doc_id PK "" + string ou "jans-fido2" + string jansConfDyn "json configuration for the app" + } +``` + +##### B. LDAP + +```mermaid +graph LR +A[ou=jans] --> V(ou=configuration) + V --> V5[ou=jans-fido2] +``` diff --git a/docs/admin/fido/vendor-metadata.md b/docs/admin/fido/vendor-metadata.md index 263c941ff16..dc35f404f5c 100644 --- a/docs/admin/fido/vendor-metadata.md +++ b/docs/admin/fido/vendor-metadata.md @@ -1,7 +1,237 @@ --- tags: - administration - - fido + - fido2 + - metadata Service + - attestation --- -This page will be the landing page for the Janssen Project admin documentation +### Metadata Service: + +The metadata service is a centralized, trusted database of FIDO authenticators. It is used by the Relying Party to validate authenticators i.e. attest the genuine-ness of a device. If implemented in organizations like government, federal agencies, banking and healthcare organizations for example) and/or organizations handling sensitive data (media companies, R&D institutions, corporations, etc), this information can help protect organizations against security vulnerabilities. + +### 1. Local metadata service: +Janssen's FIDO server has a [configuration parameter](./config.md) called `serverMetadataFolder` which by default points to a directory location `/etc/jans/conf/fido2/server_metadata` where the administrator can (obtain from a vendor and ) place authenticator metadata in json format. + +Example of authenticator metadata: +``` +{ + "aaguid": "83c44309-....-8be444b573cb", + "metadataStatement": { + "legalHeader": "Submission of this statement and retrieval and use of this statement indicates acceptance of the appropriate agreement located at https://fidoalliance.org/metadata/metadata-legal-terms/.", + "aaguid": "83c44309-....-8be444b573cb", + "description": "Just an example", + "authenticatorVersion": 448962, + "protocolFamily": "fido2", + "schema": 3, + "upv": [ + { + "major": 1, + "minor": 0 + }, + { + "major": 1, + "minor": 1 + } + ], + "authenticationAlgorithms": [ + "ed25519_eddsa_sha512_raw", + "secp256r1_ecdsa_sha256_raw" + ], + "publicKeyAlgAndEncodings": [ + "cose" + ], + "attestationTypes": [ + "basic_full" + ], + "userVerificationDetails": [ + [ + { + "userVerificationMethod": "passcode_external", + "caDesc": { + "base": 64, + "minLength": 4, + "maxRetries": 8, + "blockSlowdown": 0 + } + }, + { + "userVerificationMethod": "presence_internal" + } + ], + [ + { + "userVerificationMethod": "passcode_external", + "caDesc": { + "base": 64, + "minLength": 4, + "maxRetries": 8, + "blockSlowdown": 0 + } + } + ], + [ + { + "userVerificationMethod": "fingerprint_internal", + "baDesc": { + "selfAttestedFRR": 0, + "selfAttestedFAR": 0, + "maxTemplates": 5, + "maxRetries": 5, + "blockSlowdown": 0 + } + }, + { + "userVerificationMethod": "presence_internal" + } + ], + [ + { + "userVerificationMethod": "none" + } + ], + [ + { + "userVerificationMethod": "fingerprint_internal", + "baDesc": { + "selfAttestedFRR": 0, + "selfAttestedFAR": 0, + "maxTemplates": 5, + "maxRetries": 5, + "blockSlowdown": 0 + } + } + ], + [ + { + "userVerificationMethod": "presence_internal" + } + ] + ], + "keyProtection": [ + "hardware", + "secure_element" + ], + "matcherProtection": [ + "on_chip" + ], + "cryptoStrength": 128, + "attachmentHint": [ + "external", + "wired" + ], + "tcDisplay": [], + "attestationRootCertificates": [ + "MII....psmyPzK+Vsgw2jeRQ5JlKDyqE0hebfC1tvFu0CCrJFcw==" + ], + "icon": "data:image/png;base64,iVBORw0KGgoAAAA....k5+36hF7vXAAAAAElFTkSuQmCC", + "authenticatorGetInfo": { + "versions": [ + "FIDO_2_0", + "FIDO_2_1_PRE", + "FIDO_2_1" + ], + "extensions": [ + "credProtect", + "hmac-secret", + "largeBlobKey", + "credBlob", + "minPinLength" + ], + "aaguid": "83c.....73cb", + "options": { + "plat": false, + "rk": true, + "clientPin": true, + "up": true, + "uv": false, + "pinUvAuthToken": true, + "largeBlobs": true, + "ep": false, + "bioEnroll": false, + "userVerificationMgmtPreview": false, + "authnrCfg": true, + "credMgmt": true, + "credentialMgmtPreview": true, + "setMinPINLength": true, + "makeCredUvNotRqd": false, + "alwaysUv": true + }, + "maxMsgSize": 1200, + "pinUvAuthProtocols": [ + 2, + 1 + ], + "maxCredentialCountInList": 8, + "maxCredentialIdLength": 128, + "transports": [ + "usb" + ], + "algorithms": [ + { + "type": "public-key", + "alg": -7 + }, + { + "type": "public-key", + "alg": -8 + } + ], + "maxSerializedLargeBlobArray": 1024, + "forcePINChange": false, + "minPINLength": 4, + "firmwareVersion": 328965, + "maxCredBlobLength": 32, + "maxRPIDsForSetMinPINLength": 1, + "preferredPlatformUvAttempts": 3, + "uvModality": 2, + "remainingDiscoverableCredentials": 25 + } + }, + "statusReports": [ + { + "status": "FIDO_CERTIFIED_L1", + "effectiveDate": "2021-08-06", + "url": "www.yubico.com", + "certificationDescriptor": "An example", + "certificateNumber": "FIDO2.....001", + "certificationPolicyVersion": "1.3", + "certificationRequirementsVersion": "1.4" + }, + { + "status": "FIDO_CERTIFIED", + "effectiveDate": "2021-08-06" + } + ], + "timeOfLastStatusChange": "2021-08-16" + } +``` + + +### 2. Metadata service for authenticators approved by [FIDO Alliance (MDS3)](https://fidoalliance.org/metadata/) + +Metadata entries for trusted authenticators registered with FIDO Alliance can be found on - https://fidoalliance.org/certification/fido-certified-products/ + +![Metadata](../../assets/fido2_metadata.png) + +Draw.io reference for image: +``` + +7Vlbc6M2FP41nrYPyXAx2Hl07HUv052kdWe7fVRAAU0EokLEdn/9noOEsQBnva6ZnZ3ZJ3M+ISG+79yEJ/4y2/0sSZG+FzHlE8+JdxN/NfE8158F8IPIXiOzYKqBRLLY3NQCG/YfNaBj0IrFtLRuVEJwxQobjESe00hZGJFSbO3bngW3n1qQhPaATUR4H/2bxSrV6DxwWvwXypK0ebLrmJGMNDcboExJLLZHkP9u4i+lEEpfZbsl5Uhew4uetz4xetiYpLk6Z0L6cRW7f/0ZB+E2cD9U+8dy+ceNUeeV8Mq88G8kL2/Wv64eEN9Q+Uql2b/aN6SUW5ZxkoN1/yxyZVRz52Cb9ahUdHdyo+7h9cFvqMioknu4xUyY+oYx4zJzY25b/g9Yesx9aEBiNE8OS7e0wIVh5gtY8nssIUGALDhnJI/oDyUY76kiMVGk5ooomuH7wm7yGJ1WVqW2olQMMJqSAi9zoZDVbcoU3RQkQmwLkQVYqjKOLMPlE4leEimqPH6oFGc5NXhM5MsDzGIKqXNuneBcRU47x0mZvMBSaRr0VLoL+iLNg5E0mvY0+l1AGNu6bFpdvn0B3FlHgbCnwGxAgdlYCsx6CvRYpnm8wKQMVsRJWbLI5rWmlOJDnJO5hca9jH0ZjUc8BQPppMEk5USxV/uZQ+SZJzwKVsf9zqbbiORNO0mqFJWMqJl0nL7fXsf1O+soIhOqeuvUSh5e+nJxwy9NgVg6GISPF3KFEQM5L0zw6sdUKSzeC9yjt35msSBmjVshE9zdYZX1Tz0Xsl3kM3E6QnUKHLs6+d655amr/NUCbz4QeJp1fH+LvvDfSjQDN2XNDOjguF6xq+lpxhuxoGPJuSBIOPZYBWw2JBmynD+Vhb6R6wlr/TA9rycbEK5sbQhnSY6JAIiHHsO/R1kYpOyFGchYHOP0e0lhp+SpXgpFL9DJaxKD+0mwwrUqJUqjM5ilkuKFLgWHSospXXcqjPMuNL57eGHfPVxvwD1G8467/+8d8xPe0aSASqVAD2insLU5zyEujmPvOkK5ri3UoXE/Fmo2FMfeWEo1OxqvggI3cv/RDNbGP3WfEjTmanc8uNo31o4pnObeOk5obD0TD3jabqeicTzzkUoGDGGQ19gZddxAuji+RZlpzXX1+1z9+lo9gD/r1Iy7C5uAqddZqJs1Ru4CXHd0D208zfKyt33siv5091XdZN6pHe6lbtI5QfdOxmO7iTdeR7JQiuLxmon8e+9hlzS/W9L8fkkb6kxHaz3c/oeTq/UenabD+QB559vpPuzDnD/UJA4pNR9Nqf7nk6tFLLCiyAvFLUDIOsNNoxNhBD6jeRTZ7amxe+7QX9UkTViJEYzUAXOH1ZsT5fcU0el65x3PG/q4OlTiLvi2Cmb7dVuXlvY/Av/dJw== +``` + +Janssen's FIDO2 server - + +1. Downloads, verifies and caches metadata BLOBs from the FIDO Metadata Service. +1. Re-downloads the metadata BLOB when it expires. +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-metadata.png b/docs/assets/fido2-metadata.png new file mode 100644 index 00000000000..ee72dce5f1b Binary files /dev/null and b/docs/assets/fido2-metadata.png differ