Skip to main content

Register FIDO Device

Users can register a compatible device to act as a FIDO authenticator. To do so, some information about the device needs to be requested during a process known as attestation.

As defined in the FIDO2 Specifications,attestation is the capability of a FIDO-based authenticator (such as a security key or mobile device) to provide a cryptographic proof about its model to a remote relying party. Once this information is received, the device can be registered to an account.

Once a device is registered it can be used to authenticate users.

Registration 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 tenant username, typically your full email address
  • dns: Current domain as used in your browser
  • communityName: tenant community name as shown in the dashboard
  • displayName: Username to display
  • attestation: Attestation object - see below
  • authenticatorSelection: Authenticator selection - see below

Request Format​

Step 1: FIDO Device Attestation (Registration) Options​

caution

The attestation and authenticatorSelection parameters differ depending on what type of FIDO device you are registering:

  • If your device is a security key, such as a YubiKey:
const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');

let attestationOptionsResponse = await ​BIDWebAuthn.fetchAttestationOptions({ "dns": "<dns>", "communityName": "<communityName>", "licenseKey": "<licenseKey>" }, {
    "displayName":"<displayname>",
    "username":"<username>",
    "dns":"<current domain>",
    "attestation":"direct"
    "authenticatorSelection": {
      "requiresResidentKey":true 
    },
});
  • If your device is a platform authenticator, such as TouchID:
const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');

let attestationOptionsResponse = await ​BIDWebAuthn.fetchAttestationOptions({ "dns": "<dns>", "communityName": "<communityName>", "licenseKey": "<licenseKey>" }, {
    "displayName":"<displayname>",
    "username":"<username>",
    "dns":"<current domain>",
    "attestation":"direct"
    "authenticatorSelection": {
      "authenticatorAttachment": "platform"
    },
});
  • If your device is a MacBook:
const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');

let attestationOptionsResponse = await ​BIDWebAuthn.fetchAttestationOptions({ "dns": "<dns>", "communityName": "<communityName>", "licenseKey": "<licenseKey>" }, {
    "displayName":"<displayname>",
    "username":"<username>",
    "dns":"<current domain>",
    "attestation":"none"
    },
});

Example Registration Options Request​

We"ve provided an example request showing the registration options flow.

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.fetchAttestationOptions({
    username: 'john.doe@company.com',
    displayName: 'MyDevice',
    attestation: 'direct',
    authenticatorSelection: {
      authenticatorAttachment: 'platform'
    },
    dns: 'blockid-trial.1kosmos.net'
})

Example Registration Options Response​

200 OK
 {
			"rp": {
				"name": "1kfido.blockid.co","id":"1kfido.blockid.co",
			},
			"user": {
				"id": "u_G6bV8cwxY11ODyVcxR-ySp08a2EY6_9P8DQ8eojwg",
				"name": "john.doe",
				"displayName": "john.doe"
			},
			"attestation": "none",
			"pubKeyCredParams": [{
				"type": "public-key",
				"alg": -7
			}],
			"timeout": 60000,
			"authenticatorSelection": {
				"userVerification": "preferred",
				"requireResidentKey": false
			},
			"challenge":"ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKSVV6STFOaUo5LmV5SnlZVzVrSWpvaWIyeDZTV1ZMVDBacE1XVjJOazlKY1ZGaGEwNXdkVkZtU25abGVXUTRTa0pYTTJKRmJ6WTNVU0lzSW1GMVpDSTZJakZyWm1sa2J5NWliRzlqYTJsa0xtTnZJaXdpYzNWaUlqb2lhbTlvYm01a2IyVXlJaXdpWVhWMGFITmxiR1ZqZEdsdmJpSTZJaUlzSW1GMGRHVnpkR0YwYVc5dUlqb2libTl1WlNJc0ltbGtJam9pTlhKT1UweFNMVE5QYlVwMlpVNDVlV1JHTW00eldWRlFObGhGT1VSd1QwWlVUbE54UlZnNGJGSk9SU0lzSW1WNGNDSTZNVFkwTnpneU9EazJOMzAuNkNwMTVHRVVQcjMtd0JFdV84UlVXUXpEOGMxc0V3S1NnS19JcXBVYnhwQQ",
			"excludeCredentials": [{
				"type": "string",
				"id": "string"
			}, {...}
			],
			"status": "ok",
			"errorMessage": ""
}

Registration Result​

Once the device registration (attestation) options are returned, the device can be registered.

Parameters​

  • rawId: Registration result raw ID
  • attestationObject: Registration attestation object
  • getAuthenticatorData: Authenticator data
  • getPublicKey: Device public key
  • getPublicKeyAlgorithm: Device public key algorithm
  • getTransports: Device transports
  • clientDataJSON: Client data in JSON format
  • authenticatorAttachment: Device attachment type
  • getClientExtensionResults: Extension results
  • id: Registration result ID
  • type: Public-key
  • dns: Current domain

Request Format​

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 Registration (attestation) Result​

BIDWebAuthn.submitAttestationResult({
    rawId: '<rawId>',
    response: {
      attestationObject: '<attestationObject>',
      getAuthenticatorData: {},
      getPublicKey: {},
      getPublicKeyAlgorithm: {},
      getTransports: {},
      clientDataJSON: '<clientDataJSON>'
    },
    authenticatorAttachment: '<authenticatorAttachment>',
    getClientExtensionResults: '<getClientExtensionResults>',
    id: '<id>',
    type: '<type>',
    dns: '<current domain>'
})

Example Registration Result Request​

We've provided an example registration result:

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'
);
const BIDWebAuthn = require('blockid-nodejs-helpers/BIDWebAuthn.js');
BIDWebAuthn.submitAttestationResult({
{
  rawId: "C-4WjulifnXA7CXCsb-7Xg",
  response: {
    attestationObject: "o2NmbXRmcGFja2VkZ2F0dFN0bXSjY2FsZyZjc2lnWEYwRAIgOfSsUdb_JXdEfR5u4StcbGkxa546MBqbPw1A1H6F7CgCIDkka7ikVaNPdgq75f7plZUTYWwxHUQlNBmc9g5CAGOFY3g1Y4FZAsIwggK-MIIBpqADAgECAgRbFqi2MA0GCSqGSIb3DQEBCwUAMC4xLDAqBgNVBAMTI1l1YmljbyBVMkYgUm9vdCBDQSBTZXJpYWwgNDU3MjAwNjMxMCAXDTE0MDgwMTAwMDAwMFoYDzIwNTAwOTA0MDAwMDAwWjBvMQswCQYDVQQGEwJTRTESMBAGA1UECgwJWXViaWNvIEFCMSIwIAYDVQQLDBlBdXRoZW50aWNhdG9yIEF0dGVzdGF0aW9uMSgwJgYDVQQDDB9ZdWJpY28gVTJGIEVFIFNlcmlhbCAxNTI4MjExNjM4MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE6VGEMwI5_-3OVyN2VxRHG9LtRT4IyhAB-2PGEVAfKqAyD1bDFKE34dhZDimKpi5vVikfHdkx1YRdRlXA_qq-VaNsMGowIgYJKwYBBAGCxAoCBBUxLjMuNi4xLjQuMS40MTQ4Mi4xLjEwEwYLKwYBBAGC5RwCAQEEBAMCBDAwIQYLKwYBBAGC5RwBAQQEEgQQFJogIY72QTOWuIH41bfx9TAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3DQEBCwUAA4IBAQCnqCd5BmJXpxn3dSRRp6SMrCL_D4MVn9m6CMyeOpmIeZHSR8_YASr-08RH6-iT8WKf1NbWyPgEa1WM2yJR84WpuV_ekk_HHAce6tZL_5DKgSPFAC3E16rBiK0D5p29Koaz2I8KZsrO2IoNOgaW_3s048xSS9qqtfwme5AC7AdvX-ifoOKNDGw8zz4hypgzAoNV5whdnM402RfjK7DvdcHkk4DwarDhiZHDh-7sNejTruo7AE8LnzQeA7k-MRyxwGEyzdyf3mUPzTrIRg0EkFWU__Ui0zrVfMyPlBC16JQBE-OT1rddTddfAalXULzadGdVi7_dR4AvHrucqcKbPEBRaGF1dGhEYXRhWKJJlg3liA6MaHQ0Fw9kdmBbj-SuuaKGMseZXPO6gx2XY8UAAAAEFJogIY72QTOWuIH41bfx9QAQC-4WjulifnXA7CXCsb-7XqUBAgMmIAEhWCAlBIW9qW0_9zKSyqHzA0mkw9MoboPiipO4PIgIznj32CJYION6_VfWiEtwvHrtuUEGT6JQnA94E69XoxZKz_RlnKcvoWtjcmVkUHJvdGVjdAI",
    getAuthenticatorData: {},
    getPublicKey: {},
    getPublicKeyAlgorithm: {},
    getTransports: {},
    clientDataJSON: {
      "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiWlhsS01HVllRV2xQYVVwTFZqRlJhVXhEU21oaVIyTnBUMmxLU1ZWNlNURk9hVW81TG1WNVNubFpWelZyU1dwdmFVNHdiSFpPTTJoRlVrWlpNbFZYY0hCWmJEZzBVVEJhUjFOVVl6SmFTRTVSWkd4U2JFMXRNVVpUVkZKU1RqQmtNbFJxYURaUFEwbHpTVzFHTVZwRFNUWkpiWGgyV1RKR2MyRkhPWHBrUTBselNXNU9NVmxwU1RaSmJYQnNZbTFzZW1GRE1IaEphWGRwV1ZoV01HRklUbXhpUjFacVpFZHNkbUpwU1RaSmFVbHpTVzFHTUdSSFZucGtSMFl3WVZjNWRVbHFiMmxhUjJ4NVdsZE9NRWxwZDJsaFYxRnBUMmxKZEZONldUTldWVFZyWVRGU1JGRnRPV3RSVkZwTFRqTlZNV1ZzUmpObFJGWlpWVEJWZW1GdVVtaGlWR1JUV2xob1ZsUnRPWEJVU0dSV1NXbDNhVnBZYUhkSmFtOTRUbXBSTlU1cVl6Tk9hazE2WmxFdVUzY3RORVZPUVUxclgwWmxTalJUY1hkWFpWaEplakZEVGxGS2REWlBkbGxhZG5aV1NqRlJOMEl4VVEiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJjcm9zc09yaWdpbiI6ZmFsc2V9"
      },
    authenticatorAttachment: "cross-platform",
    getClientExtensionResults: {},
    id: "C-4WjulifnXA7CXCsb-7Xg",
    type: "public-key",
    dns: "blockid-trial.1kosmos.net"
}

Example Registration Result Response​

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