Register a device with the Hanko FIDO UAF Client

In order to register a device using the Hanko FIDO UAF Client and the Hanko API, the following three steps must be performed:

Step 1: Retrieve a registration request
Step 2: Pass the registration request to the Hanko FIDO UAF Client
Step 3: Send the public key to the Hanko API

Hanko FIDO UAF Client registration flow — Sequence diagram for the UAF registration flow with the Hanko FIDO UAF Client for Android

Step 1: Retrieve a registration request

The first step consists of initiating the registration of an authenticator device by issuing a POST request to the UAF endpoint ({API_URL}/v1/uaf/requests) of the Hanko API. The POST request body must include the appropriate operation type (i.e. REG for registration), a userId and a username. The userId will be used to map a public key credential generated during registration to a specific user account with the relying party. As mentioned in the prerequisites, you need an HTTP client to make a request to your backend. In your backend you can use one of the server-side Hanko SDKs to initiate the registration with the Hanko API. This request targets a secured endpoint of the API, so you will need an API Key ID and an API Key (see the prerequisites).

http POST {API_URL}/v1/uaf/requests \
 'Authorization:secret pasteYourApiKeySecretHere' \
 'operation=REG' \
 'username=example@example.com' \
 'userId=exampleId'

curl -X POST "{API_URL}/v1/uaf/requests" \
-H 'Authorization:secret pasteYourApiKeyHere' \
-H 'Content-Type: application/json' \
-d '{"operation": "REG", "username":"example@example.com", "userId":"exampleId" }'

The API will respond with a Hanko request in a PENDING status. It contains the registration request issued by the FIDO server which must be passed to the Hanko FIDO UAF Client in order to trigger credential creation and prompting the user for an authentication gesture.

{
  "id": "<requestId>",
  "request": "<fido-uaf-request>",
  "operation": "REG",
  "username": "example@example.com",
  "userId": "exampleId",
  "status": "PENDING",
  ...
}

Remember to cache the returned Hanko request because the request id will be required to finalize the registration in Step 3.

Step 2: Pass the registration request to the Hanko FIDO UAF Client

Android
iOS

Extract the request value from the Hanko request you retrieved in the previous step.Create a stringified representation of a JSON object with the following structure:

{
    "uafProtocolMessage": "<request>"
}

Use Android’s Intent mechanism to pass it to the Hanko FIDO UAF Client (<fido-uaf-request>). This will trigger a prompt for an authentication gesture. To retrieve the activity result, use the startActivityForResult API.

Intent intent = new Intent(context, io.hanko.fidouafclient.FidoUafClient.class);
intent.setType("application/fido.uaf_client+json");
intent.putExtra("UAFIntentType", "UAF_OPERATION");
intent.putExtra("channelBindings", "{}");
intent.putExtra("message", "<fido-uaf-request>");

startActivityForResult(intent, REQUEST_CODE);

After the user accepted or denied the request by performing an authentication gesture, you can process the result using the onActivityResult API.

protected void onActivityResult(int requestCode, int resultCode, Intent data) {
	if(resultCode == RESULT_OK && requestCode == REQUEST_CODE) {
		short errorCode = data.getShortExtra("errorCode", (short) 0xFF);
		if(errorCode == 0x00) { // errorCode 0x00 means success
			try {
				JSONObject jsonObject = new JSONObject(data.getStringExtra("message")); // 1.
                String uafResponse = jsonObject.getString("uafProtocolMessage"); // 1.
				// verify uafResponse
			} catch(JSONException ex) {
				// TODO
			}
		} else {
			// some error occured, use errorCode for determination
		}
	}
}

Extract the response (1) from the Intent data. The extracted value will be used in the next step to verify the authenticator response.

Extract the request value from the Hanko request you retrieved in the previous step and create a UAFMessage (<fido-uaf-request> is the request value).

let uafMessage = UAFMessage(uafProtocolMessage: "<fido-uaf-request>")

Pass the UAFMessage to the client’s process method.

FidoClient.process(uafMessage: uafMessage) { resultMessage, error in
	// send resultMessage to Hanko API
}

After the user accepted or denied the request by performing an authentication gesture, send the authenticator response (resultMessage) to the Hanko API in the next step.

Step 3: Send the public key to the Hanko API

To finalize the registration by verifying the authenticator response, use an HTTP client in your app to forward the authenticator response along with the requestId of the initialization request (see Step 1) to your backend. Then, use a Hanko server-side SDK to pass the authenticator response to the Hanko API. This request targets a secured endpoint so you will need an API Key ID and an API Key. Reuse a previously instantiated client instance or create one as described in Step 1.

Backend SDK examples for this step will be added once official server SDKs are available again.

After registration is successful you can choose to persist information that a user has registered a device (e.g. using Shared Preferences, UserDefaults) such that - for example - subsequent authentication attempts automatically use the registered credential.

Getting started

Quickstarts

Guides

SDKs & Plugins

API Reference

Register a device with the Hanko FIDO UAF Client

Step 1: Retrieve a registration request

Step 2: Pass the registration request to the Hanko FIDO UAF Client

Step 3: Send the public key to the Hanko API

​Step 1: Retrieve a registration request

​Step 2: Pass the registration request to the Hanko FIDO UAF Client

​Step 3: Send the public key to the Hanko API

Step 1: Retrieve a registration request

Step 2: Pass the registration request to the Hanko FIDO UAF Client

Step 3: Send the public key to the Hanko API