enface-auth-node v1.0.23

Enface authorization Node.js library

Enface offers biometric authorization feature for any websites (or apps) using Enface application and neural networks face recognition engine. Our authentication process is based on strong cryptographic algorithms combined with biometric user's data.

To enable our solution you should pass the following steps:

• Register for free at Enface website, visit �Biometric authorization�page and click on the �Add new project� button. Setup �API key for authentication� from the drop-down of the project panel. Copy the �Project id� and �Secret key� variables for future usage.
• Integrate the frontend widget on your website or application.
• Setup backend environment, using instructions below.

This package is for backend integration with Node.js environment. There are 2 different modes of backend functionality � using WebSockets or Express web server. WebSockets are recommended way of backend operation, but requires an additional port to be opened for connections. Instead of WebSockets, you can provide any existing Express instance to enable HTTP/S mode.

Installation

npm

npm i --save enface-auth-node

yarn

yarn add enface-auth-node

Usage

ES2015 module import:

import { EnfaceAuth } from "enface-auth-node";

CommonJS module require:

const { EnfaceAuth } = require("enface-auth-node ");

Initialization:

new EnfaceAuth({

	port: <number> || httpServer: <object>,
	callbackUrl: <string>,
	projectId: <string>,
	secretCode: <string>,
	debug: <boolean> // debug logs
	
	onCheckCurrentStatus(userId) {
		// is biometric sign in for current user enabled or not?
	},
	
	onUserValidate(userData) {
		// validate logged in user by token, session id, cookie etc.
	},
	
	onActivate(userId, bioId, userPublicKey) {
		// linking user with his biometric id
	},
	
	onUserTokenByBioId(bioId) {
		// create athorization data and send it to the frontend
	},
	
});

Backend preparations:

To activate biometric authorization on any resource with its current user base it is required to create any kind of permanent storage with linking info. There should be at least 3 kind of data fields in each stored record:

• internal user id (any searchable type to identify your user)
• biometric id provided by Enface service upon activation (UUID)
• application RSA public key (TEXT, up to 1kb)

EnfaceAuth parameters and callbacks (all functions can be asynchronous):

port (integer)

If this variable is set, EnfaceAuth module is going to start in WebSockets mode and will try to open specified port to listen all incoming connections. In this mode both frontend widget and Enface API server should be able to connect to ws(s)://yourdomain.com:port to process required operation and checks.

httpServer (Express instance)

If this variable is set, EnfaceAuth module will start in HTTP/S mode and will use default Express port to listen all the connections. In this mode both frontend widget and Enface API server should connect to http(s)://yourdomain.com to process required operation and checks.

Important: only one of the variables (port or httpServer) should be set, otherwise there will be an exception thrown by the EnfaceAuth library.

callbackUrl: <string>

ws(s) or http(s) URL to connect to this backend module, constructed regarding �port� or �httpServer� variables above.

projectId: <string>

�Project id� variable from the Enface website project description.

secretCode: <string>

�Secret key� variable from the Enface website project description.

onCheckCurrentStatus(userId): <boolean>

This callback used to determine the state of current user biometric authorization state (turned ON or OFF). Here the link of �userId� with his �bioId� should be checked and returned (see example below).

onUserValidate(userData) : <any>

This function is used to determine �userId� by secured identification data, sent from the frontend (token, session id, cookie etc.).

onActivate(userId, bioId, userPublicKey) : <boolean>

This function will be called after Enface API server processes the enable/disable user request, providing �userId� (determined in �onUserValidate�), �bioId� (calculated by Enface using user biometric data) and �userPublicKey� from the Enface application in PEM encoding (string up to 1kb).

• If the backend table contains any records with this �userId", they should be deleted and "false�returned (Biometric sign in is turned OFF);
• If the backend storage do not contains any record with this �userId� - a new record, containing �userId�, �bioId� and �userPublicKey� should be created. The result of the callback must be �true� in this case (Biometric sign in is turned ON).

onUserPublicKey(userId) : <string>

To achieve maximum security level, the Enface application instance will be checked using asynchronous cryptography. �userPublicKey�, stored at �onActivate� stage should be received here, to accomplish these checks. Perform the search using provided �userId� and return the value, if any.

onUserTokenByBioId(bioId) : <any>

This function will be called after Enface API server successfully processed the authorization request, providing �bioId� to find the linked �userId�. At this moment an authorization data (token, session id, cookies etc.) should be generated according your backend security logic. All necessary security checks are already done at this moment and Enface Widget at the frontend is going to receive generated token.

###Here is how EnfaceAuth is integrated at our own Node.js server.

new EnfaceAuth({

  httpServer: app, // app is the existing Express instance
  projectId: process.env.AUTH_PRODUCT_ID,
  secretCode: process.env.BIO_AUTH_SECRET,
  callbackUrl: 'https://enface-api-server.herokuapp.com',
  // full callback URL (we use HTTPS mode as we provide �httpServer� variable above)

	async onCheckCurrentStatus(userId) {
		// record with �userId� existence means that biometric signin is enabled
		const bioUser = await models.AuthBioLink.findByUserId(userId);
		return !!bioUser;
	},

	onUserValidate(userData) {
		// frontend widget will send this JWT token to identify user
		const token = jwt.verify(userData, process.env.JWT_SECRET);
		return token.id;
	},

	async onActivate(userId, bioId, userPublicKey) {
		// checking the �userId� record existance
		const bioUser = await models.AuthBioLink.findByUserId(userId);
		if (bioUser) { // delete record and return �false�. Biometric is now turned OFF
			await bioUser.destroy({ userId });
			return false;
		}

		// add new record and return �true�. Biometric is now turned ON
		await models.AuthBioLink.create({
			userId,
			bioId,
			userPublicKey,
		});
		return true;
	},

	async onUserPublicKey(userId) {
		// just get user public key if record with �userId� exists
		const bioUser = await models.AuthBioLink.findByUserId(userId);
		return bioUser ? bioUser.userPublicKey : null;
	},

	async onUserTokenByBioId(bioId) {
		// look for a record with �bioId"
		const bioUser = await models.AuthBioLink.findByBioId(bioId);
		if (!bioUser) return false; // no records found

		// look for the user record in main users table (we know �userId�)
		const user = await models.User.findById(bioUser.userId);
		if (!user || !user.isActive) return false;

		/*
		* use your backend custom authorization logic here
		* the main goal at this moment is to generate secutity token
		* which will be sent to Enface Widget automatically
		* and let the user continue authorized
		*/

		// here is how we do it: generate and return JWT token
		return utils.createToken(user, process.env.SECRET, constants.SESSION_JWK_TIMEOUT);
	},
});