FIDO2 APIs for Native Android Applications

Ideem's FIDO2 Authenticator interfaces can be used to integrate with an existing Relying Party infrastructure. A Relying Party server is responsible for managing the storage of credential_ids and public keys associated with enrollments, generating challenges, and verifying signed challenges.

These interfaces allow you to determine if a user has already been enrolled (cryptographically bound to the device), create an enrollment if they have not, or verify them. FIDO2 Authenticator WebAuthn functions can be used to provide a silent second factor after strong authentication, as well as reverification when needed for transactions requiring step up authentication.

Interface Definitions

Jump to: Kotlin, Java

Getting the version number of the SDK library: FIDO2Client.versionString

To retrieve the version number of the SDK library use the class property FIDO2Client.versionString. It will return the version number in semantic versioning format, major.minor.patch.

Kotlin

Retrieving Enrollment Status: FIDO2Client.webauthnRetrieve()

There are two versions of this method: one for retrieving credentials for the current user, and another for retrieving credentials for a specific user.

For Current User

The webauthnRetrieve method checks if the current user has previously registered credentials on this device and retrieves the enrollment status.

Usage

client.webauthnRetrieve { response ->
    if (response != null) {
        val rawId = response.getString("rawId")
        // Handle retrieved attestation data
    } else {
        Log.e("FIDO2ClientViewModel", "Error retrieving attestation data")
    }
}

Parameters

Returns

The callback function returns the following parameter:

For Specific User

The webauthnRetrieve method with a user parameter checks if a specific user has previously registered credentials on this device and retrieves the enrollment status.

Usage

val userId = "user123" // Unique identifier for the user
client.webauthnRetrieve(userId) { response ->
    if (response != null) {
        val rawId = response.getString("rawId")
        // Handle retrieved attestation data for specific user
    } else {
        Log.e("FIDO2ClientViewModel", "Error retrieving attestation data for user: $userId")
    }
}

Parameters

Returns

The callback function returns the following parameter:

Enrolling (Attestation): FIDO2Client.webauthnCreate()

The webauthnCreate method initiates the creation of a new credential object using the specified PublicKeyCredentialCreationOptions. The generated credential object can be stored securely for future authentication.

The response follows the PublicKeyCredential format from the WebAuthn standard.

Refer to Mozilla's online documentation on PublicKeyCredentialCreationOptions or to the W3C standard Options for Credential Creation. For response format, see the W3C standard PublicKeyCredential interface.

Usage

client.webauthnCreate(optionsJsonObject) { result, metadata, error ->
    if (result != null) {
        val rawId = result.getString("rawId")
        // Handle successful creation, store or use the rawId
    } else if (error != null) {
        Log.e("FIDO2ClientViewModel", "Error during creation: ${error.localizedMessage}")
    }
}

Parameters

Returns

The callback function returns the following parameters:

Verifying (Assertion): FIDO2Client.webauthnGet()

The webauthnGet method retrieves a credential object based on the specified PublicKeyCredentialRequestOptions. This object can be used to authenticate the user.

The response follows the AuthenticatorAssertionResponse format from the WebAuthn standard.

Refer to Mozilla's online documentation on PublicKeyCredentialRequestOptions or to the W3C standard Options for Assertion Generation. For response format, see the W3C standard AuthenticatorAssertionResponse interface.

Usage

client.webauthnGet(optionsJsonObject) { result, metadata, error ->
    if (result != null) {
        // Handle successful assertion
    } else if (error != null) {
        Log.e("FIDO2ClientViewModel", "Error during assertion: ${error.localizedMessage}")
    }
}

Parameters

Returns

The callback function returns the following parameters:

Unbind: FIDO2Client.unbind()

There are two versions of this method: one for removing all FIDO2 credentials for the current user, and another for removing credentials for a specific user.

For Current User

The unbind method removes all FIDO2 credentials and state for the current user from the device.

Usage

client.unbind { success ->
    if (success) {
        Log.d("FIDO2ClientViewModel", "Successfully unbind FIDO2 state for current user")
    } else {
        Log.e("FIDO2ClientViewModel", "Failed to unbind FIDO2 state")
    }
}

Parameters

Returns

The callback function returns the following parameter:

For Specific User

The unbind method with a user parameter removes FIDO2 credentials and state for a specific user from the device.

Usage

val userId = "user123" // Unique identifier for the user
client.unbind(userId) { success ->
    if (success) {
        Log.d("FIDO2ClientViewModel", "Successfully unbind FIDO2 state for user: $userId")
    } else {
        Log.e("FIDO2ClientViewModel", "Failed to unbind FIDO2 state for user: $userId")
    }
}

Parameters

Returns

The callback function returns the following parameter:

Java

Retrieving Enrollment Status: FIDO2Client.webauthnRetrieve()

There are two versions of this method: one for retrieving credentials for the current user, and another for retrieving credentials for a specific user.

For Current User

The webauthnRetrieve method checks if the current user has previously registered credentials on this device and retrieves the enrollment status.

Usage

client.webauthnRetrieve(response -> {
    if (response != null) {
        try {
            String rawId = response.getString("rawId");
            // Handle retrieved attestation data
        } catch (JSONException e) {
            Log.e("FIDO2ClientViewModel", "Error parsing JSON response: " + e.getMessage());
        }
    } else {
        Log.e("FIDO2ClientViewModel", "Error retrieving attestation data");
    }
});

Parameters

The WebAuthnRetrieveCompletionHandler interface has a single method:

void onComplete(JSONObject result);

Returns

The callback function returns the following parameter:

For Specific User

The webauthnRetrieve method with a user parameter checks if a specific user has previously registered credentials on this device and retrieves the enrollment status.

Usage

String userId = "user123"; // Unique identifier for the user
client.webauthnRetrieve(userId, response -> {
    if (response != null) {
        try {
            String rawId = response.getString("rawId");
            // Handle retrieved attestation data for specific user
        } catch (JSONException e) {
            Log.e("FIDO2ClientViewModel", "Error parsing JSON response: " + e.getMessage());
        }
    } else {
        Log.e("FIDO2ClientViewModel", "Error retrieving attestation data for user: " + userId);
    }
});

Parameters

Returns

The callback function returns the following parameter:

Enrolling (Attestation): FIDO2Client.webauthnCreate()

The webauthnCreate method initiates the creation of a new credential object using the specified PublicKeyCredentialCreationOptions. The generated credential object can be stored securely for future authentication.

Refer to Mozilla's PublicKeyCredentialCreationOptions documentation or the W3C Options for Credential Creation.

Usage

client.webauthnCreate(optionsJsonObject, (result, metadata, error) -> {
    if (result != null) {
        try {
            String rawId = result.getString("rawId");
            // Handle successful creation, store or use the rawId
        } catch (JSONException e) {
            Log.e("FIDO2ClientViewModel", "Error parsing JSON response: " + e.getMessage());
        }
    } else if (error != null) {
        Log.e("FIDO2ClientViewModel", "Error during creation: " + error.getLocalizedMessage());
    }
});

Parameters

The WebAuthnCompletionHandler interface has a single method:

void onComplete(JSONObject result, Map<String, String> metadata, ZSMError error);

Returns

The callback function returns the following parameters:

Verifying (Assertion): FIDO2Client.webauthnGet()

The webauthnGet method retrieves a credential object based on the specified PublicKeyCredentialRequestOptions. This object can be used to authenticate the user.

Refer to Mozilla's PublicKeyCredentialRequestOptions documentation or the W3C Options for Assertion Generation.

Usage

client.webauthnGet(optionsJsonObject, (result, metadata, error) -> {
    if (result != null) {
        // Handle successful assertion
    } else if (error != null) {
        Log.e("FIDO2ClientViewModel", "Error during assertion: " + error.getLocalizedMessage());
    }
});

Parameters

Returns

The callback function returns the following parameters:

Unbind: FIDO2Client.unbind()

There are two versions of this method: one for removing all FIDO2 credentials for the current user, and another for removing credentials for a specific user.

For Current User

The unbind method removes all FIDO2 credentials and state for the current user from the device.

Usage

client.unbind(success -> {
    if (success) {
        Log.d("FIDO2ClientViewModel", "Successfully unbound FIDO2 state for current user");
    } else {
        Log.e("FIDO2ClientViewModel", "Failed to unbind FIDO2 state");
    }
});

Parameters

The BooleanCompletionHandler interface has a single method:

void onComplete(boolean success);

Returns

The callback function returns the following parameter:

For Specific User

The unbind method with a user parameter removes FIDO2 credentials and state for a specific user from the device.

Usage

String userId = "user123"; // Unique identifier for the user
client.unbind(userId, success -> {
    if (success) {
        Log.d("FIDO2ClientViewModel", "Successfully unbound FIDO2 state for user: " + userId);
    } else {
        Log.e("FIDO2ClientViewModel", "Failed to unbind FIDO2 state for user: " + userId);
    }
});

Parameters

Returns

The callback function returns the following parameter: