Product Documentation

The following request body is sent during the preregister call:

  • URL: https://<FQDN>:<PORT>/skfs/rest/preregister

  • HTTP Method: POST

  • FIDO2_0 request body:
    {
      "svcinfo": {
        "did": 1,
        "protocol": "FIDO2_0",
        "authtype": "PASSWORD",
        "svcusername": "svcfidouser",
        "svcpassword": "Abcd1234!"
      },
      "payload": {
        "username": "johndoe",
        "displayname": "Initial Registration",
        "options": {
          "attestation": "direct"
        },
        "extensions": "{}",
        "appTXID": "exampleappTXID"
      }
    }

svcinfo Description

Value

Explanation

did

Unique identifier for an SKFS cryptographic domain. Unless you are 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.

payload Description

Value

Explanation

username

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 EU General Data Protection Regulation, a.k.a. GDPR, or the California Consumer Privacy Act, a.k.a. 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 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.

displayname

A label assigned to the unique authenticator used by the user when registering with SKFS.

If this is the first registration (a.k.a. the “genesis registration”) of the user with the application using SKFS, it is recommended the web application assign a fixed name to such genesis registrations such as “Initial Registration” or something equivalent. Since a well-designed FIDO application will allow the user to assign “user-friendly” names to additional authenticators they register with SKFS—such as “iPhone Key,” “HP laptop,” “Blue Security Key," etc.—having the “Initial Registration” will allow the original registration to be distinguishable from all other authenticators.

NOTE: FIDO allows users to have as many authenticators to access the application as they might choose. It is reasonable for users to have multiple authenticators to access web applications in case they lose one; this will allow users to use an alternate authenticator to access the account, and delete the lost authenticator credential.

options

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

AttestationConveyancePreference

UserVerification

requireResidentKey

AuthenticatorAttachment

NOTE: While the options provide applications some flexibility. SKFS has a powerful Policy Module that makes application development more efficient, enabling security organizations to effectively manage security policy without the need to code similar behaviors 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.

extensions

A JSON object containing an optional list of extensions the web application may request of SKFS to associate with this registration request. The optional extensions are intended to tailor the authenticator types the web application is willing to accept. The parameter can be empty. To learn more about extensions, please visit this site.

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.