README.md

Yoti NodeJS SDK

Welcome to the Yoti NodeJS SDK. This repo contains the tools you need to quickly integrate your NodeJS back-end with Yoti, so that your users can share their identity details with your application in a secure and trusted way.

An architectural view

To integrate your application with Yoti, your back-end must expose a GET endpoint that Yoti will use to forward tokens. The endpoint can be configured in Yoti Dashboard when you create/update your application.

The image below shows how your application back-end and Yoti integrate in the context of a Login flow. Yoti SDK carries out for you steps 6, 7 ,8 and the profile decryption in step 9.

Yoti also allows you to enable user details verification from your mobile app by means of the Android (TBA) and iOS (TBA) SDKs. In that scenario, your Yoti-enabled mobile app is playing both the role of the browser and the Yoti app. By the way, your back-end doesn't need to handle these cases in a significantly different way. You might just decide to handle the User-Agent header in order to provide different responses for web and mobile clients.

Enabling the SDK

To import the Yoti SDK inside your project, you can use your favourite dependency management system. If you are using NPM, you need to add the following dependency:

"dependencies": {
    "yoti-node-sdk" : "1.0.0"
}

Windows installation

If you're planning on using the Node SDK on Windows, you'll need to install a few dependencies first:

• OpenSSL (normal version, not light) in the same bitness as your Node.js installation.
  • OpenSSL must be installed in its specific directory (C:\OpenSSL-Win32 or C:\OpenSSL-Win64)
  • The latest version of OpenSSL (v1.1.x) does not have the libeay32.dll file. Install v1.0.2 instead.
  • If you get Error: The specified module could not be found., copy libeay32.dll from the OpenSSL bin directory to this module's bin directory, or to Windows\System32.
• node-gyp (npm install -g node-gyp)
  • Either install Microsoft's windows-build-tools using npm install --global --production windows-build-tools
  • Or manually install Python 2.7 and Visual Studio (or modify an existing installation) and select Common Tools for Visual C++ during setup.

Client initialisation

The YotiClient is the SDK entry point. To initialise it you need include the following snippet inside your endpoint initialisation section:

const YotiClient = require('yoti-node-sdk')
const APPLICATION_ID = 'your-app-id'
const PEM = fs.readFileSync("path/to/your-application-pem-file.pem")
var yotiClient = new YotiClient(APPLICATION_ID, PEM)

Where:

• APPLICATION_ID is the identifier generated by Yoti Dashboard when you create your app.
• path/to/your-application-pem-file.pem is the path to the pem file your browser generates for you, when you create your app on Yoti Dashboard.

Profile retrieval

When your application receives a token via the exposed endpoint (it will be assigned to a query string parameter named token), you can easily retrieve the user profile by adding the following to your endpoint handler:

yotiClient.getActivityDetails(token).then((activityDetails) => {
	//handle response here
})

Before you inspect the user profile, you might want to check whether the user validation was successful. This is done as follows:

yotiClient.getActivityDetails(token).then((activityDetails) => {
	if(activityDetails.getOutcome() == 'SUCCESS') {
		profile = activityDetails.getUserProfile();
	} else {
		// handle unhappy path
	}
})

Handling users

When you retrieve the user profile, you receive a userId generated by Yoti exclusively for your application. This means that if the same individual logs into another app, Yoti will assign her/him a different id. You can use such id to verify whether the retrieved profile identifies a new or an existing user. Here is an example of how this works:

yotiClient.getActivityDetails(token).then((activityDetails) => {
	if(activityDetails.getOutcome() == 'SUCCESS') {
		user = yourUserSearchFunction(activityDetails.getUserId());
		if(user) {
			// handle login
		} else {
			// handle registration
		}
	} else {
		// handle unhappy path
	}
})

Where yourUserSearchFunction is a piece of logic in your app that is supposed to find a user, given a userId. No matter if the user is a new or an existing one, Yoti will always provide her/his profile, so you don't necessarily need to store it.

The profile object provides a set of attributes corresponding to user attributes. Whether the attributes are present or not depends on the settings you have applied to your app on Yoti Dashboard.

Running tests

npm test