Request

The following request body is sent during the preauthenticate call:

URL: https://<FQDN>:<PORT>/skfs/rest/preauthenticate
HTTP Method: POST

FIDO2_0 request body:

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

svcinfo Description

Value	Explanation
did	Unique identifier for a cryptographic domain within SKFS. Unless using a StrongKey Tellaro appliance, this defaults to 1.
protocol	The FIDO protocol to be used in this request (FIDO2_0).
authtype	The type of authentication supplied in this service request—it must be PASSWORD or HMAC (see API Security for details); the example shown here is for PASSWORD type of authentication.
svcusername	The username of the service credential requesting this web service.
svcpassword	The password of the service credential requesting this web service. When PASSWORD authtype is used, SKFS uses entries in a previously configured Lightweight Directory Access Protocol (LDAP) or Active Directory (AD) to authenticate the credential (see <Manage Service Credentials> under SKFS->Administration->Security for details).

payload Description

Value	Explanation
username	Support for discoverable credentials has been added to SKFS starting with version 4.10. This will allow relying parties to implement username-less authentication flow. To initiate a discoverable flow during authentication, the "username" input parameter for the preauthenticate web service has been made optional. The "username" input param can either be set to NULL or an empty value or it can be completely removed from the input JSON. If a username is provided, this is the name assigned by the web application to the user account registering the FIDO credential. NOTE: While it is traditional for web applications to register users with their e-mail addresses, new privacy regulations (such as the GDPR or the California Consumer Privacy Act aka CCPA) might require that applications protect this personally identifiable information (PII). It is recommended that applications get the e-mail address from the user as part of the registration process, but that applications also generate a randomly generated string—such as a UUID—as the username in this web service. This will ensure that the SKFS database holds no information that could be deemed PII. Applications may choose to still prompt users for their e-mail address to identify them; but once identified, the web application could lookup the UUID associated with that user and use it in this parameter to register a FIDO credential for the user.
options	A JSON object containing an optional list of features the web application may request of the SKFS to associate with this authentication request. The optional features are intended to tailor the types of Authenticators the web application is willing to accept digital signatures from. The JSON object can contain one or more of the following options—but may also be empty to convey no specific preference: UserVerification NOTE: While the options provide applications some flexibility, SKFS has a powerful Policy Module to make application development more efficient. It enables Security organizations to manage security policy more effectively without the need to write such code into applications. It is recommended that applications take advantage of Predefined Policies supplied by SKFS—or modify one of them—to manage FIDO security within the web application.
appTXID	An optional string within any SKFS web service request body's payload JSON object that, if added, will attach the appTXID value to the TXID logged by the server.

Value

Explanation

username

Support for discoverable credentials has been added to SKFS starting with version 4.10. This will allow relying parties to implement username-less authentication flow.

To initiate a discoverable flow during authentication, the "username" input parameter for the preauthenticate web service has been made optional. The "username" input param can either be set to NULL or an empty value or it can be completely removed from the input JSON.

If a username is provided, this is the name assigned by the web application to the user account registering the FIDO credential.

NOTE: While it is traditional for web applications to register users with their e-mail addresses, new privacy regulations (such as the GDPR or the California Consumer Privacy Act aka CCPA) might require that applications protect this personally identifiable information (PII).

It is recommended that applications get the e-mail address from the user as part of the registration process, but that applications also generate a randomly generated string—such as a UUID—as the username in this web service. This will ensure that the SKFS database holds no information that could be deemed PII.

Applications may choose to still prompt users for their e-mail address to identify them; but once identified, the web application could lookup the UUID associated with that user and use it in this parameter to register a FIDO credential for the user.

options

A JSON object containing an optional list of features the web application may request of the SKFS to associate with this authentication request. The optional features are intended to tailor the types of Authenticators the web application is willing to accept digital signatures from. The JSON object can contain one or more of the following options—but may also be empty to convey no specific preference:

UserVerification

NOTE: While the options provide applications some flexibility, SKFS has a powerful Policy Module to make application development more efficient. It enables Security organizations to manage security policy more effectively without the need to write such code into applications. It is recommended that applications take advantage of Predefined Policies supplied by SKFS—or modify one of them—to manage FIDO security within the web application.

appTXID

An optional string within any SKFS web service request body's payload JSON object that, if added, will attach the appTXID value to the TXID logged by the server.