StrongKey FIDO Server (SKFS) supports authenticating users with "discoverable credentials". Registration flow for "discoverable credentials" does not differ from the general FIDO Registration flow. However, Authentication flow for "discoverable credentials" is different from the general FIDO Authentication flow. The most important difference is that the "username" input parameter for the preauthenticate web service has been made optional.

PLEASE NOTE: You can either use the two-step flow (General use case) or the custom three-step flow designed for a specific use case. By default, the property “skfs.cfg.property.retainauthenticatechallenge” is set to "false" during the installation. Setting this to "true" will allow for the custom three-step flow for “discoverable credentials”.

Enabling the general two-step flow for Discoverable in SKFS

• Switch to (or login as) the strongkey user

  shell> su - strongkey

• Edit the skfs properties file

  shell> vi /usr/local/strongkey/skfs/etc/skfs-configuration.properties

• Set skfs.cfg.property.retainauthenticatechallenge to false.

  skfs.cfg.property.retainauthenticatechallenge=false

• Restart the Payara using the following command:

  shell> sudo systemctl restart payara

   

Enabling the custom three step flow for Discoverable in SKFS

• Switch to (or login as) the strongkey user

  shell> su - strongkey

• Edit the skfs properties file

  shell> vi /usr/local/strongkey/skfs/etc/skfs-configuration.properties

• Set skfs.cfg.property.retainauthenticatechallenge to true.

  skfs.cfg.property.retainauthenticatechallenge=true

• Restart the Payara using the following command:

  shell> sudo systemctl restart payara

   

Following is the detailed explanation on how the Authentication works for Discoverable in two and three steps flow:

STEP 1 (GENERAL FLOW): CALL PREAUTHENTICATE WEB SERVICE

The web application sends a preauthenticate request. The "username" input parameter is optional.

{
    "svcinfo": {
        "did": 1,
        "protocol": "FIDO2_0",
        "authtype": "PASSWORD",
        "svcusername": "svcfidouser",
        "svcpassword": "Abcd1234!"
    },
    "payload": {
        "username": "",
        "options": {}
    }
} 

In response, SKFS returns an empty "allowCredentials" array

{
    "Response": {
        "challenge": "nd54MgbnS0RkFZhBgwQtGg",
        "allowCredentials": [],
        "rpId": "strongkey.com"
    },
    "responseCode": "FIDO-MSG-0006"
}

STEP 2 (GENERAL FLOW): CALL AUTHENTICATE WEB SERVICE TO GET USERNAME

The web application will convert the preauthenticate response to a challenge buffer to be used by the browser in a window.navigator.credentials.get call.

The web application calls the authenticate web service, however, there is no username provided.

Authenticate request

{
    "svcinfo": {
        "did": 1,
        "protocol": "FIDO2_0",
        "authtype": "PASSWORD",
        "svcusername": "svcfidouser",
        "svcpassword": "Abcd1234!"
    },
    "payload": {
        "publicKeyCredential": {
            "id": "ICg6T0HYY9lJekClKWL7inmT5OrWrabxRjHhzOLcJ456cpzWaVgk_9D0GJZCOmyq",
            "rawId": "ICg6T0HYY9lJekClKWL7inmT5OrWrabxRjHhzOLcJ456cpzWaVgk_9D0GJZCOmyq",
            "response": {
                "authenticatorData": "WnTBrV2dI2nYtpWAzOrzVHMkwfEC46dxHD4U1RP9KKMFAAAACw",
                "signature": "MEUCIBHnIq3odQlNctwbk_XxLkxIclbUQlyBuHTmjL0E5ScLAiEAgizvFG55Nz-Yb47JkJXGuxOEqgRLKVDwxUhtrF1bJIY",
                "userHandle": "Gz0xMbW7QnQuLsHM9T0InFprZNWViumado5tikOX94c",
                "clientDataJSON": "eyJjaGFsbGVuZ2UiOiJuZDU0TWdiblMwUmtGWmhCZ3dRdEdnIiwib3JpZ2luIjoiaHR0cHM6Ly9kZW1vLnN0cm9uZ2tleS5jb206ODE4MSIsInR5cGUiOiJ3ZWJhdXRobi5nZXQifQ=="
            },
            "type": "public-key"
        },
        "strongkeyMetadata": {
            "version": "1.0",
            "last_used_location": "Sunnyvale,CA",
            "username": "",
            "origin": "https://demo.strongkey.com:8181"
        }
    }
}

In response, the SKFS returns a username and the web application should fetch the username from the response.

{
    "Response": "Successfully processed authentication response",
    "responseCode": "FIDO-MSG-0008",
    "username": "johndoe",
    "jwt": "",
    "skfsVersion": "4.14.0",
    "registrationVersion": "4.14.0",
    "skfsFQDN": "example.strongkey.com",
    "TXID": "1-1-77-1717793850650"
}

STEP 3 (CUSTOM FLOW)– CALL AUTHENTICATE WEB SERVICE

 As a final step, the web application calls the authenticate web service with a username and gets a response from SKFS:

Authenticate request

{
    "svcinfo": {
        "did": 1,
        "protocol": "FIDO2_0",
        "authtype": "PASSWORD",
        "svcusername": "svcfidouser",
        "svcpassword": "Abcd1234!"
    },
    "payload": {
        "publicKeyCredential": {
            "id": "ICg6T0HYY9lJekClKWL7inmT5OrWrabxRjHhzOLcJ456cpzWaVgk_9D0GJZCOmyq",
            "rawId": "ICg6T0HYY9lJekClKWL7inmT5OrWrabxRjHhzOLcJ456cpzWaVgk_9D0GJZCOmyq",
            "response": {
                "authenticatorData": "WnTBrV2dI2nYtpWAzOrzVHMkwfEC46dxHD4U1RP9KKMFAAAACw",
                "signature": "MEUCIBHnIq3odQlNctwbk_XxLkxIclbUQlyBuHTmjL0E5ScLAiEAgizvFG55Nz-Yb47JkJXGuxOEqgRLKVDwxUhtrF1bJIY",
                "userHandle": "Gz0xMbW7QnQuLsHM9T0InFprZNWViumado5tikOX94c",
                "clientDataJSON": "eyJjaGFsbGVuZ2UiOiJuZDU0TWdiblMwUmtGWmhCZ3dRdEdnIiwib3JpZ2luIjoiaHR0cHM6Ly9kZW1vLnN0cm9uZ2tleS5jb206ODE4MSIsInR5cGUiOiJ3ZWJhdXRobi5nZXQifQ=="
            },
            "type": "public-key"
        },
        "strongkeyMetadata": {
            "version": "1.0",
            "last_used_location": "Sunnyvale,CA",
            "username": "johndoe",
            "origin": "https://demo.strongkey.com:8181"
        }
    }
}

Authenticate Response:

{
    "Response": "Successfully processed authentication response",
    "responseCode": "FIDO-MSG-0008",
    "username": "johndoe",
    "jwt": "",
    "skfsVersion": "4.14.0",
    "registrationVersion": "4.14.0",
    "skfsFQDN": "example.strongkey.com",
    "TXID": "1-1-77-1717793850650"
}