FIDO2 RP API

HYPR SDK for Java

Prior to Server release 7.7, HYPR SDK for Java only implemented a single FIDO2 API. The existing call was intended for device retrieval; the functions and endpoints for clarity: fetchFido2Devices that was using the endpoint /rp/api/versioned/fido2/user.

Included in release 7.7 and moving forward, all remaining FIDO2 APIs have been ported over as well and are available via several new API clients implemented into the SDK. These API clients, and subsequently the endpoints for which they are responsible, each have relative Java beans available to represent all expected payloads and responses from the APIs.

πŸ“˜

API Access Tokens

All of these endpoints require a valid API token that is provided via a HYPRConfiguration object parameter used to initialize the API Client. This follows the same functionality of the API clients existing prior to release 7.7.

The API clients can be imported to whichever class functionality from these endpoints is needed, with the objects specified below relating to each API call. The respective Java objects for requests and responses each contain attributes directly relating to the structure of API calls in HYPR’s API documentation.

Fido2ApplicationAPIClient

updateFido2AppSettings(Fido2AppSettingsReq req)

Update FIDO2 settings for a specific application. The rpAppId field in the request object must be the same as the rpAppId bound to the access token.

  • Associated Objects: Fido2AppSettingsReq Fido2AppSettingsResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/settings

getFido2AppSettings()

This function does not require any parameter or request object; it retrieves FIDO2 settings for the RP Application bound to the provided access token. See the FIDO2 specification for reference.

  • Associated Objects: Fido2AppSettingsResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/settings

getFido2AppConfig(Integer version)

This call does not require a request object, just version provided as an Int. This call retrieves a list of FIDO2-related configuration objects for the RP Application bound to the provided access token. The operation fails if FIDO2 is disabled for this RP Application.

  • Associated Objects: Fido2AppConfigResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/app?version=4

deleteFido2AppConfig(Integer version)

This function does not require any parameter or request object. This call deletes all FIDO2-related configuration objects for the RP Application bound to the provided access token. The operation fails if FIDO2 is disabled for this RP Application.

  • Associated Objects: Fido2AppDeleteConfigResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/app

Fido2AuthenticationAPIClient

assertionOptions(Fido2AssertionOptionsReq req)

This represents the first part of FIDO2 authentication flow, in which HYPR generates public key request options for the navigator.credentials.get JavaScript call.

  • Associated Objects: Fido2AssertionOptionsReq Fido2AssertionOptionsResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/assertion/options

assertionOptions(Fido2AssertionOptionsReq req)

The second part of FIDO2 authentication flow, in which an authentication assertion is sent to HYPR for validation. See the FIDO2 specification for reference.

  • Associated Objects: Fido2AssertionResultReq Fido2AssertionResultResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/attestation/result

Fido2RegistrationAPIClient

attestationOptions(Fido2AttestationOptionReq req)

This is the first part of FIDO2 device registration flow, in which HYPR generates public key creation options for the navigator.credentials.create JavaScript call. See the FIDO2 specification for reference.

  • Associated Objects: Fido2AttestationOptionsReq Fido2AttestationOptionsResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/attestation/options

attestationResult(Fido2AttestationResultReq req)

The second part of the FIDO2 device registration flow, in which FIDO2 attestation data is submitted to HYPR for validation and storage. See the FIDO2 specification for reference.

  • Associated Objects: Fido2AttestationResultReq Fido2AssertionResultResp
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/attestation/result

Fido2DeviceAPIClient

getUserDevices(String username)

This call does not require a request object; just username as a string. It retrieves the number of registered FIDO2 devices for the given user and the RP Application bound to the provided access token. In addition it returns a Boolean of whether or not the user is registered.

  • Associated Objects: returns Fido2UserStatusResponse
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/user/status?username={{fido2-username}}

getUserDevices(String username)

This call does not require a request object; just a username as a string. It retrieves a list of FIDO2 devices registered for the given user and the RP Application bound to the provided access token.

Device information contains the following fields:

{
    "appId": "RP Application ID retrieved from the access token",
    "aaid": "AAGUID of the FIDO2 device",
    "username": "username provided in the request parameter",
    "displayName": "Display variant of the username",
    "publicKey": "Public key of the FIDO2 device",
    "keyId": "Key ID of the FIDO2 device",
    "signCounter": 1590441721,
    "authenticatorAttachment": "Authenticator type: platform or cross-platform",
    "locked": false,
    "userHandle": "",
    "publicKeyType": "Example: EC2",
    "publicKeyAlg": "Example: ES256",
    "createDate": Registration create time in epoch millis
}
  • Associated Objects: returns List<Fido2RegisteredDevice>
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/user?username={{fido2-username}}

deleteFido2Device(String username, String keyId)

This call does not require a request object, just the username and device keyId as strings. It will delete (de-register) a FIDO2 device with the given keyId registered for the given username and the given RP Application bound to the provided access token.

  • Associated Objects: returns DeleteFido2DeviceResponse
  • Respective API: {{baseUrl}}/rp/api/versioned/fido2/user?username={{fido2-username}}&keyId={{fido2-key-id}}

FIDO Metadata Service (MDS)

As of version 7.2, HYPR SDK for Java's FIDO MDS v3 API updates the metadata daily, obviating the need to make manual updates.

Should you desire to test security functions outside the standard MDS, the HYPR SDK for Java FIDO RP API supports manual API calls for MDS v3 only.

MDS v2 API calls will not work.