Authenticate Using FIDO Device

Users can authenticate login requests and other requests using a registered FIDO device.

Authentication Options

Some basic user account and tenant information is needed to register a device. This information can be found on the Developer Dashboard.

Parameters

• username: Registered username
• dns: Current domain as used in your browser, such as localhost
• displayName: Username to display

Request Format

NodeJS

Step 1: Set tenant info

const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');
const BIDSDK = require('blockid-nodejs-helpers/BIDSDK.js');
const loaded = await BIDSDK.setupTenant(
  { dns: '<current domain>', communityName: '<community name>' },
  '<tenant license key>'
);

Step 2: Request FIDO authentication (assertion) options

BIDWebAuthn.fetchAssertionOptions({
  username: '<username>',
  displayName: '<displayName>',
  dns: '<current domain>',
});

PHP

Step 1: Set tenant info

<?php
require_once("./BIDTenant.php");
require_once("./BIDWebAuthn.php");

$tenantInfo = array("dns" => "<dns>", "communityName" => "<communityName>", "licenseKey" => "<licenseKey>");

Step 2: Request FIDO authentication (assertion) options

$optionsRequest = array(
    "username" => "<username>",
    "displayName" => "<displayName>",
    "dns" => "<current domain>"
);

$assertionOptionsResponse = BIDWebAuthn::fetchAssertionOptions($tenantInfo, $optionsRequest);
?>

Java

Step 1: Set tenant info

BIDTenantInfo tenantInfo = new BIDTenantInfo("<dns>", "<communityName>", "<tenant license key>");

Step 2: Request FIDO authentication (assertion) options

BIDAssertionOptionValue assertionOptionRequest = new BIDAssertionOptionValue();
	assertionOptionRequest.username = "<username>";
    assertionOptionRequest.displayName = "<displayName>";
    assertionOptionRequest.dns = "<current domain>";

BIDAssertionOptionResponse assertionOptionResponse = BIDWebAuthn.fetchAssertionOptions(tenantInfo, assertionOptionRequest);

.NET

Step 1: Import libraries and set tenant info

using BIDHelpers.BIDWebAuthn;
using BIDHelpers.BIDWebAuthn.Model;
using BIDHelpers.BIDTenant.Model;

BIDTenantInfo bidTenantInfo = new BIDTenantInfo("<dns>", "<communityName>", "<license>");

Step 2: Request FIDO authentication (assertion) options

BIDAssertionOptionValue assertionOptionRequest = new BIDAssertionOptionValue
    {
        username = "<username>",
        displayName = "<displayName>",
        dns = "<current domain>"
    };
BIDAssertionOptionResponse assertionOptionResponse = BIDWebAuthn.FetchAssertionOptions(bidTenantInfo, assertionOptionRequest);

Example Authentication Options Request

We've provided an example request showing the authentications options flow.

NodeJS

const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');
const BIDSDK = require('blockid-nodejs-helpers/BIDSDK.js');
const loaded = await BIDSDK.setupTenant(
  { dns: 'blockid-trial.1kosmos.net', communityName: 'devx' },
  '24b4e0df-29ed-488d-bfe1-000000000000'
);

BIDWebAuthn.fetchAssertionOptions({
  username: 'john.doe@company.com',
  displayName: 'MyDevice',
  dns: 'blockid-trial.1kosmos.net',
});

PHP

<?php
require_once("./BIDTenant.php");
require_once("./BIDWebAuthn.php");

$tenantInfo = array("dns" => "blockid-trial.1kosmos.net", "devx" => "<communityName>", "licenseKey" => "24b4e0df-29ed-488d-bfe1-000000000000");

$optionsRequest = array(
    "username" => "john.doe@company.com",
    "displayName" => "MyDevice",
    "dns" => "blockid-trial.1kosmos.net"
);

$assertionOptionsResponse = BIDWebAuthn::fetchAssertionOptions($tenantInfo, $optionsRequest);

?>

Java

BIDTenantInfo tenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "24b4e0df-29ed-488d-bfe1-000000000000");

BIDAssertionOptionValue assertionOptionRequest = new BIDAssertionOptionValue();
	assertionOptionRequest.username = "john.doe@company.com";
    assertionOptionRequest.displayName = "MyDevice";
    assertionOptionRequest.dns = "blockid-trial.1kosmos.net";

BIDAssertionOptionResponse assertionOptionResponse = BIDWebAuthn.fetchAssertionOptions(tenantInfo, assertionOptionRequest);

.NET

using BIDHelpers.BIDWebAuthn;
using BIDHelpers.BIDWebAuthn.Model;
using BIDHelpers.BIDTenant.Model;

BIDTenantInfo bidTenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "24b4e0df-29ed-488d-bfe1-000000000000");

BIDAssertionOptionValue assertionOptionRequest = new BIDAssertionOptionValue
    {
        username = "john.doe@company.com",
        displayName = "MyDevice",
        dns = "blockid-trial.1kosmos.net"
    };
BIDAssertionOptionResponse assertionOptionResponse = BIDWebAuthn.FetchAssertionOptions(bidTenantInfo, assertionOptionRequest);

Example Authentication Options Response

200 OK

{
		"challenge":"XlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5SnlZVzVrSWpvaVVGbHpiRTV3V1VzeU1GcHhhVGRWYjFCUlFVTlVTekE0WjFodlNuRlBaRUl5YjJwVGRtMVhVaUlzSW1GMVpDSTZJakZyWm1sa2J5NWliRzlqYTJsa0xtTnZJaXdpYzNWaUlqb2lhbTlvYm01a2IyVXlJaXdpYVdRaU9pSjJRbGxrTlhObU5rSk9lWFpvVHpCRVZtTXlNRGxYTlU5YVQwaHlabEJCWm5Wak5scHlNVWxIVVZoeklpd2laWGh3SWpveE5qUTNPREk1TWprMGZRLkFPdjhmSlR1dnlxak9pLWx1aVgxbGVsTmkwanU4Sk85SVpLTlNVeEZBUFE",
		"rpId": "1kfido.blockid.co",
		"timeout": 60000,
		"userVerification": "preferred",
		"allowCredentials": [{
			"type": "public-key",
			"transports": ["internal"],
			"id": "string"
		}, {
			"type": "public-key",
			"transports": ["internal"],
			"id":"AdsogLw0q2c2BZI5a9G0_qqSUxMa-baLSd7moAtEFJWlD8_NGRD_hPHnqcCGoBV-dyPe3MG_cFyF5AraYTSuMNLSDuELyFpJaM_4uQ5C0DYEav8rAw"
		}, {
			"type": "public-key",
			"transports": ["usb", "ble", "nfc"...],
			"id": "string"
		}],
		"status": "ok",
		"errorMessage": ""
}

Authentication Result

Once the device authentication options have been returned you have the necessary information to authenticate requests.

Parameters

• rawId: Authentication result raw ID
• authenticatorData: Authentication options result data
• signature: Authentication options signature
• userHandle: User handle
• clientDataJSON: JSON data
• authenticatorAttachment: Platform or USB
• id: Authentication result ID

Request Format

NodeJS

Step 1: Set tenant info

const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');
const BIDSDK = require('blockid-nodejs-helpers/BIDSDK.js');
const loaded = await BIDSDK.setupTenant(
  { dns: '<current domain>', communityName: '<community name>' },
  '<tenant license key>'
);

Step 2: FIDO authentication (assertion) result

BIDWebAuthn.submitAssertionResult({
    rawId: '<rawId>',
    response: {
        authenticatorData: '<authenticatorData>',
        signature: '<signature>',
        userHandle: '<userHandle>',
        clientDataJSON: '<clientDataJSON>'
    },
    getClientExtensionResults: '<getClientExtensionResults>',
    id: '<id>',
    type: '<type>',
    dns: '<current domain>'
});

PHP

Step 1: Set tenant info

<?php
<?php
require_once("./BIDTenant.php");
require_once("./BIDWebAuthn.php");

$tenantInfo = array("dns" => "<dns>", "communityName" => "<communityName>", "licenseKey" => "<licenseKey>");

Step 2: FIDO authentication (assertion) result

$resultRequest = array(
    "rawId" => "<rawId>",
    "response" => array(
        "authenticatorData" => "<authenticatorData>",
        "signature" => "<signature>",
        "userHandle" => "<userHandle>",
        "clientDataJSON" => "<clientDataJSON>"
    ),
    "getClientExtensionResults" => "<getClientExtensionResults>",
    "id" => "<id>",
    "type" => "<type>",
    "dns" => "<current domain>"
);

$assertionResultResponse = BIDWebAuthn::submitAssertionResult($tenantInfo, $resultRequest);

?>

Java

Step 1: Set tenant info

BIDTenantInfo tenantInfo = new BIDTenantInfo("<dns>", "<communityName>", "<license>");

Step 2: FIDO authentication (assertion) result

BIDAssertionResultValue assertionResultRequest = new BIDAssertionResultValue();
	assertionResultRequest.rawId = "<rawId>";
    assertionResultRequest.dns = "<dns>";
    assertionResultRequest.response = "<response>";
    assertionResultRequest.getClientExtensionResults = "<getClientExtensionResults>";
    assertionResultRequest.id = "<id>";
    assertionResultRequest.type = "<type>";

BIDAssertionResultResponse assertionResultResponse = BIDWebAuthn.submitAssertionResult(tenantInfo, assertionResultRequest);

.NET

Step 1: Import libraries and set tenant info

using BIDHelpers.BIDWebAuthn;
using BIDHelpers.BIDWebAuthn.Model;
using BIDHelpers.BIDTenant.Model;

BIDTenantInfo bidTenantInfo = new BIDTenantInfo("<dns>", "<communityName>", "<license>");

Step 2: FIDO authentication (assertion) result

BIDAssertionResultValue assertionResultRequest = new BIDAssertionResultValue
    {
        rawId = "<rawId>",
        dns = "<dns>",
        response = new BIDAssertionResultResponseValue()
            {
                authenticatorData = "<authenticatorData>",
                signature = "<signature>",
                userHandle = "<userHandle>",
                clientDataJSON = "<clientDataJSON>",
            },
            getClientExtensionResults = "<getClientExtensionResults>",
            id = "<id>",
            type = "<type>"
    };

BIDAssertionResultResponse assertionResultResponse = BIDWebAuthn.SubmitAssertionResult(bidTenantInfo, assertionResultRequest);

Example Authentication Result Request

We've provided an example authentication result request:

NodeJS

const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');
const BIDSDK = require('blockid-nodejs-helpers/BIDSDK.js');
const loaded = await BIDSDK.setupTenant(
  { dns: 'blockid-trial.1kosmos.net', communityName: 'devx' },
  '24b4e0df-29ed-488d-bfe1-000000000000'
);

BIDWebAuthn.submitAssertionResult({
    "rawId": "C-4WjulifnXA7CXCsb-7Xg",
    "response": {
        "authenticatorData": "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAABQ",
        "signature": "MEUCIQCpQNf1bEy6LYsFOeSEDzElii7o3YE1aTHnFdF7_cnyWAIgaKOkTt9hP74KJfWSeRzBtjmeYTM3bRI01yRCFcGa4Ks",
        "userHandle": "-K67UNdkTCBodA6J7u5zQwx5XSE3jtam7RexUNoiLwU",
        "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU21oaVIyTnBUMmxLU1ZWNlNURk9hVW81TG1WNVNubFpWelZyU1dwdmFXRllXVEJQVldnMFVraFNUbFpIVWxoaU0zQnlZV3RPZUUxVE1VNU9WVW95VVRGT1NFNVlVbFZXTWpRMFpXcFNNMWRXVm14VVEwbHpTVzFHTVZwRFNUWkpiWGgyV1RKR2MyRkhPWHBrUTBselNXNU9NVmxwU1RaSmJYQnNZbTFzZW1GRE1IaEphWGRwWVZkUmFVOXBTa2RVYlZaMlZWWnJNbVZFVW5SVmF6RnVWMVJrVGxack5UTmpTR2MxWVRCMFQyTkhiM2xWUmtwUVVUTktWMUZYY0VaaWJtaHdXRE5TTTBscGQybGFXR2gzU1dwdmVFNXFVVFZPYW1NelRucHJlR1pSTGtWYVMwZ3dYMkYzU0RBMVZYUnlUSEpQTW5OSU1tWmFaSHAxVkVsa1p5MWtNRlZYVmxFd1YzUXhRa0UiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9"
    },
    "getClientExtensionResults": {},
    "id": "C-4WjulifnXA7CXCsb-7Xg",
    "type": "public-key",
    "dns": "blockid-trial.1kosmos.net"
}

PHP

<?php
require_once("./BIDTenant.php");
require_once("./BIDWebAuthn.php");

$tenantInfo = array("dns" => "blockid-trial.1kosmos.net", "communityName" => "devx", "licenseKey" => "24b4e0df-29ed-488d-bfe1-000000000000");

$resultRequest = array(
    "rawId" => "C-4WjulifnXA7CXCsb-7Xg",
    "response" => array(
        "authenticatorData" => "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAABQ",
        "signature" => "MEUCIQCpQNf1bEy6LYsFOeSEDzElii7o3YE1aTHnFdF7_cnyWAIgaKOkTt9hP74KJfWSeRzBtjmeYTM3bRI01yRCFcGa4Ks",
        "userHandle" => "-K67UNdkTCBodA6J7u5zQwx5XSE3jtam7RexUNoiLwU",
        "clientDataJSON" => "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU21oaVIyTnBUMmxLU1ZWNlNURk9hVW81TG1WNVNubFpWelZyU1dwdmFXRllXVEJQVldnMFVraFNUbFpIVWxoaU0zQnlZV3RPZUUxVE1VNU9WVW95VVRGT1NFNVlVbFZXTWpRMFpXcFNNMWRXVm14VVEwbHpTVzFHTVZwRFNUWkpiWGgyV1RKR2MyRkhPWHBrUTBselNXNU9NVmxwU1RaSmJYQnNZbTFzZW1GRE1IaEphWGRwWVZkUmFVOXBTa2RVYlZaMlZWWnJNbVZFVW5SVmF6RnVWMVJrVGxack5UTmpTR2MxWVRCMFQyTkhiM2xWUmtwUVVUTktWMUZYY0VaaWJtaHdXRE5TTTBscGQybGFXR2gzU1dwdmVFNXFVVFZPYW1NelRucHJlR1pSTGtWYVMwZ3dYMkYzU0RBMVZYUnlUSEpQTW5OSU1tWmFaSHAxVkVsa1p5MWtNRlZYVmxFd1YzUXhRa0UiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9"
    ),
    "getClientExtensionResults" => "",
    "id" => "C-4WjulifnXA7CXCsb-7Xg",
    "type" => "public-key",
    "dns" => "blockid-trial.1kosmos.net"
);

$assertionResultResponse = BIDWebAuthn::submitAssertionResult($tenantInfo, $resultRequest);
?>

Java

BIDTenantInfo tenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "24b4e0df-29ed-488d-bfe1-000000000000");

BIDAssertionResultResponseValue response = new BIDAssertionResultResponseValue();
	response.authenticatorData = "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAABQ";
	response.signature = "MEUCIQCpQNf1bEy6LYsFOeSEDzElii7o3YE1aTHnFdF7_cnyWAIgaKOkTt9hP74KJfWSeRzBtjmeYTM3bRI01yRCFcGa4Ks";
	response.userHandle = "-K67UNdkTCBodA6J7u5zQwx5XSE3jtam7RexUNoiLwU";
	response.clientDataJSON = "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU21oaVIyTnBUMmxLU1ZWNlNURk9hVW81TG1WNVNubFpWelZyU1dwdmFXRllXVEJQVldnMFVraFNUbFpIVWxoaU0zQnlZV3RPZUUxVE1VNU9WVW95VVRGT1NFNVlVbFZXTWpRMFpXcFNNMWRXVm14VVEwbHpTVzFHTVZwRFNUWkpiWGgyV1RKR2MyRkhPWHBrUTBselNXNU9NVmxwU1RaSmJYQnNZbTFzZW1GRE1IaEphWGRwWVZkUmFVOXBTa2RVYlZaMlZWWnJNbVZFVW5SVmF6RnVWMVJrVGxack5UTmpTR2MxWVRCMFQyTkhiM2xWUmtwUVVUTktWMUZYY0VaaWJtaHdXRE5TTTBscGQybGFXR2gzU1dwdmVFNXFVVFZPYW1NelRucHJlR1pSTGtWYVMwZ3dYMkYzU0RBMVZYUnlUSEpQTW5OSU1tWmFaSHAxVkVsa1p5MWtNRlZYVmxFd1YzUXhRa0UiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9";

BIDAssertionResultValue assertionResultRequest = new BIDAssertionResultValue();
	assertionResultRequest.rawId = "C-4WjulifnXA7CXCsb-7Xg";
    assertionResultRequest.dns = "blockid-trial.1kosmos.net";
    assertionResultRequest.response = response;
    assertionResultRequest.getClientExtensionResults = "";
    assertionResultRequest.id = "C-4WjulifnXA7CXCsb-7Xg";
    assertionResultRequest.type = "public-key;

BIDAssertionResultResponse assertionResultResponse = BIDWebAuthn.submitAssertionResult(tenantInfo, assertionResultRequest);

.NET

using BIDHelpers.BIDWebAuthn;
using BIDHelpers.BIDWebAuthn.Model;
using BIDHelpers.BIDTenant.Model;

BIDTenantInfo bidTenantInfo = new BIDTenantInfo("blockid-trial.1kosmos.net", "devx", "24b4e0df-29ed-488d-bfe1-000000000000");

BIDAssertionResultValue assertionResultRequest = new BIDAssertionResultValue
    {
        rawId = "C-4WjulifnXA7CXCsb-7Xg",
        dns = "blockid-trial.1kosmos.net",
        response = new BIDAssertionResultResponseValue()
            {
                authenticatorData = "SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAABQ",
                signature = "MEUCIQCpQNf1bEy6LYsFOeSEDzElii7o3YE1aTHnFdF7_cnyWAIgaKOkTt9hP74KJfWSeRzBtjmeYTM3bRI01yRCFcGa4Ks",
                userHandle = "-K67UNdkTCBodA6J7u5zQwx5XSE3jtam7RexUNoiLwU",
                clientDataJSON = "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU21oaVIyTnBUMmxLU1ZWNlNURk9hVW81TG1WNVNubFpWelZyU1dwdmFXRllXVEJQVldnMFVraFNUbFpIVWxoaU0zQnlZV3RPZUUxVE1VNU9WVW95VVRGT1NFNVlVbFZXTWpRMFpXcFNNMWRXVm14VVEwbHpTVzFHTVZwRFNUWkpiWGgyV1RKR2MyRkhPWHBrUTBselNXNU9NVmxwU1RaSmJYQnNZbTFzZW1GRE1IaEphWGRwWVZkUmFVOXBTa2RVYlZaMlZWWnJNbVZFVW5SVmF6RnVWMVJrVGxack5UTmpTR2MxWVRCMFQyTkhiM2xWUmtwUVVUTktWMUZYY0VaaWJtaHdXRE5TTTBscGQybGFXR2gzU1dwdmVFNXFVVFZPYW1NelRucHJlR1pSTGtWYVMwZ3dYMkYzU0RBMVZYUnlUSEpQTW5OSU1tWmFaSHAxVkVsa1p5MWtNRlZYVmxFd1YzUXhRa0UiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9",
            },
            getClientExtensionResults = "",
            id = "C-4WjulifnXA7CXCsb-7Xg",
            type = "public-key"
    };

BIDAssertionResultResponse assertionResultResponse = BIDWebAuthn.SubmitAssertionResult(bidTenantInfo, assertionResultRequest);

Example Authentication Result Response

200 OK

{
    "sub": "john.doe",
    "errorMessage": "",
    "status": "ok"
}