From f7ab3c09b988cf513dcf652a6c15f9ac31d2bcc4 Mon Sep 17 00:00:00 2001 From: David Grayston Date: Fri, 12 Jun 2020 15:49:08 +0100 Subject: [PATCH] SDK-1424: Split README --- README.md | 309 ++------------------------ docs/AML.md | 56 +++++ docs/DOCSCAN.md | 11 + docs/PROFILE.md | 194 ++++++++++++++++ login_flow.png => docs/login_flow.png | Bin examples/doc-scan/README.md | 3 + 6 files changed, 284 insertions(+), 289 deletions(-) create mode 100644 docs/AML.md create mode 100644 docs/DOCSCAN.md create mode 100644 docs/PROFILE.md rename login_flow.png => docs/login_flow.png (100%) diff --git a/README.md b/README.md index 6e1b3fa4..5eda6962 100755 --- a/README.md +++ b/README.md @@ -10,60 +10,21 @@ Welcome to the Yoti NodeJS SDK. This repo contains the tools and step by step in ## Table of Contents -1) [An Architectural View](#an-architectural-view) - -High level overview of integration - -2) [References](#references) - -Guides before you start - -3) [Requirements](#requirements) - +1) [Requirements](#requirements) - Check you have what you need -4) [Installing the SDK](#installing-the-sdk) - +1) [Installing the SDK](#installing-the-sdk) - How to install our SDK -5) [Configuration](#configuration) - -How to initialise your configuration - -6) [Profile Retrieval](#profile-retrieval) - -How to retrieve a Yoti profile using the token - -7) [Programmatic QR Code Creation](#programmatic-qr-code-creation) - -How to retrieve a QR Code link by defining the requested user profile attributes programmatically - -8) [Handling Users](#handling-users) - -How to manage users - -9) [AML Integration](#aml-integration) - -How to integrate with Yoti's AML (Anti Money Laundering) service - -10) [Running the Examples](#running-the-examples) +1) [Setup](#setup) - +Setup required before using the Yoti services -11) [API Coverage](#api-coverage) - -Attributes defined +1) [Products](#products) - +Links to more information about the products offered by the Yoti SDK -12) [Support](#support) - +1) [Support](#support) - Please feel free to reach out -## 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 Hub 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. - -![alt text](login_flow.png "Login flow") - -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. - -## References - -* [AES-256 symmetric encryption](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) -* [RSA pkcs asymmetric encryption](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) -* [Protocol buffers](https://en.wikipedia.org/wiki/Protocol_Buffers) -* [Base64 data](https://en.wikipedia.org/wiki/Base64) - ## Requirements ### Node version @@ -106,258 +67,26 @@ Your package.json file will then be updated to include: The YotiClient is the SDK entry point. To initialise it you need include the following snippet inside your endpoint initialisation section: ```javascript - const yoti = require('yoti'); const fs = require('fs'); -const CLIENT_SDK_ID = 'your sdk id'; -const PEM = fs.readFileSync(__dirname + '/keys/your-application-pem-file.pem'); +const CLIENT_SDK_ID = 'YOUR_SDK_ID'; +const PEM = fs.readFileSync('path/to/your-application-pem-file.pem'); const yotiClient = new yoti.Client(CLIENT_SDK_ID, PEM); - -``` - -Where: - -* `APPLICATION_ID` is the identifier generated by Yoti Hub when you create your app. - -* `CLIENT_SDK_ID` is the SDK identifier generated by Yoti Hub in the Key tab when you create your app. Note this is not your Application Identifier which is needed by your client-side code. - -* `path/to/your-application-pem-file.pem` is the path to the application pem file. It can be downloaded only once from the Keys tab in your Yoti Hub. - -Please do not open the pem file as this might corrupt the key and you will need to create a new application. - -[Example reference](examples/profile/index.js) - -### Upgrading from SDK version 2.x.x - -The way the Yoti SDK client is initialised was changed in version 3. Please make sure you update your code if you're upgrading the npm package. - -```javascript - -const yoti = require('yoti') -const yotiClient = new yoti.Client(CLIENT_SDK_ID, PEM) - -``` - -## 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: - -```javascript - -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: - -```javascript - -yotiClient.getActivityDetails(token).then((activityDetails) => { - if(activityDetails.getOutcome() == 'SUCCESS') { - const profile = activityDetails.getProfile(); - } else { - // handle unhappy path - } -}) - -``` - -[Example reference](examples/profile/index.js) - - -## Programmatic QR code creation - -Dynamic Policy generation is a way of requesting non-static attribute lists for your application. - -This is useful when you want or need different permutations of attributes from Yoti, without having to create a new scenario. - -E.g: - -* Request 1: full-name and date-of-birth -* Request 2: full-name and address - -This service will query Yoti for a QR Code/link associated with the requested attribute list. - -This QR Code/link should then be embedded into your page using the Yoti widget to begin a share with Yoti. - -### Example - -The following example demonstrates how a Dynamic Policy can be built using attribute methods such as `withFullName()`, and generic method `withWantedAttribute()`. - -```javascript -const wantedEmailAttribute = new yoti.WantedAttributeBuilder() - .withName('email_address') - .withAcceptSelfAsserted() - .build(); - -const dynamicPolicy = new yoti.DynamicPolicyBuilder() - .withFullName() - .withWantedAttribute(wantedEmailAttribute) - .build(); - -const dynamicScenario = new yoti.DynamicScenarioBuilder() - .withCallbackEndpoint('/profile') - .withPolicy(dynamicPolicy) - .build(); - -yotiClient.createShareUrl(dynamicScenario) - .then((shareUrlResult) => { - const shareUrl = shareUrlResult.getShareUrl(); - const refId = shareUrlResult.getRefId(); - }); - -``` - -## Handling Users - -When you retrieve the user profile, you receive a user ID 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 this ID to verify whether (for your application) the retrieved profile identifies a new or an existing user. -Here is an example of how this works: - -```javascript - -yotiClient.getActivityDetails(token).then((activityDetails) => { - if(activityDetails.getOutcome() == 'SUCCESS') { - const userProfile = activityDetails.getUserProfile(); // deprecated - const profile = activityDetails.getProfile(); - const user = yourUserSearchFunction(activityDetails.getRememberMeId()); - if(user) { - // handle login - } else { - // handle registration - const givenNames = profile.getGivenNames().getValue(); - const familyName = profile.getFamilyName().getValue(); - } - } else { - // handle unhappy path - } -}) - -``` - -Where `yourUserSearchFunction` is a piece of logic in your app that is supposed to find a user, given a _Remember Me ID_. -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 Hub. - -You can retrieve the sources and verifiers for each attribute as follows: - -```javascript -const givenNamesSources = givenNames.getSources(); // list/array of anchors -const givenNamesVerifiers = givenNames.getVerifiers(); // list/array of anchors -const givenNamesAnchors = givenNames.getAnchors(); // list/array of anchors -``` - -You can also retrieve further properties from these respective anchors in the following way: - -```javascript -// Retrieving properties of the first anchor -const type = givenNamesSources[0].getType(); // string -const value = givenNamesSources[0].getValue(); // string -const subtype = givenNamesSources[0].getSubType(); // string -const timestamp = givenNamesSources[0].getSignedTimeStamp().getTimestamp(); // Date object -const originServerCerts = givenNamesSources[0].getOriginServerCerts(); // list of X509 certificates ``` -## AML Integration +## Setup -Yoti provides an AML (Anti Money Laundering) check service to allow a deeper KYC process to prevent fraud. This is a chargeable service, so please contact [sdksupport@yoti.com](mailto:sdksupport@yoti.com) for more information. +For each service you will need: -Yoti will provide a boolean result on the following checks: +* Your Client SDK ID, generated by [Yoti Hub](https://hub.yoti.com) when you create (and then publish) your app. +* Your .pem file. This is your own unique private key which your browser generates from the [Yoti Hub](https://hub.yoti.com) when you create an application. -* PEP list - Verify against Politically Exposed Persons list -* Fraud list - Verify against US Social Security Administration Fraud (SSN Fraud) list -* Watch list - Verify against watch lists from the Office of Foreign Assets Control +## Products -To use this functionality you must ensure your application is assigned to your organisation in the Yoti Hub - please see [here](https://developers.yoti.com/yoti-app/web-integration#step-1-creating-an-organisation) for further information. - -For the AML check you will need to provide the following: - -* Data provided by Yoti (please ensure you have selected the Given name(s) and Family name attributes from the Data tab in the Yoti Hub) - * Given name(s) - * Family name -* Data that must be collected from the user: - * Country of residence (must be an ISO 3166 3-letter code) - * Social Security Number (US citizens only) - * Postcode/Zip code (US citizens only) - -### Consent - -Performing an AML check on a person *requires* their consent. -**You must ensure you have user consent *before* using this service.** - -### Code example - -Given a YotiClient initialised with your SDK ID and KeyPair (see [Configuration](#configuration)) performing an AML check is a straightforward case of providing basic profile data. - -```javascript - -// Initiate user profile data. - -const amlAddress = new yoti.AmlAddress('GBR'); -const amlProfile = new yoti.AmlProfile('Edward Richard George', 'Heath', amlAddress); - -yotiClient.performAmlCheck(amlProfile).then((amlResult) => { - console.log(amlResult.isOnPepList); - console.log(amlResult.isOnFraudList); - console.log(amlResult.isOnWatchList); - - // Or - console.log(amlResult); -}).catch((err) => { - console.error(err); -}) - -``` - -## Running the Examples - -### Follow instructions in the README for each example: -* [Profile](examples/profile) -* [AML](examples/aml-check) -* [Doc Scan](examples/doc-scan) - -## API Coverage - -In order to get the users information, the Node SDK will decrypt the token in the callback URL. Use the following code to do this: - -```javascript - -yotiClient.getActivityDetails(token).then((activityDetails) => { - const userProfile = activityDetails.getProfile(); - // Use the table below to retrieve specific attributes from the profile object -}) -``` - -* Activity Details - * [X] Remember Me ID `getRememberMeId()` - * [X] Parent Remember Me ID `getParentRememberMeId()` - * [X] Receipt ID `getReceiptId()` - * [X] Timestamp `getTimestamp()` - * [X] Base64 Selfie Uri `getBase64SelfieUri()` - * [X] Profile `getProfile()` - * [X] Full Name `getFullName().getValue()` - * [X] Given Names `getGivenNames().getValue()` - * [X] Family Name `getFamilyName().getValue()` - * [X] Age / Date of Birth `getDateOfBirth().getValue()` - * [X] Age / Verify Condition `getAgeVerified().getValue()` - * [X] Gender `getGender().getValue()` - * [X] Nationality `getNationality().getValue()` - * [X] Mobile Number `getPhoneNumber().getValue()` - * [X] Photo `getSelfie().getValue()` - * [X] Email Address `getEmailAddress().getValue()` - * [X] Address `getPostalAddress().getValue()` - * [X] Structured Address `getStructuredPostalAddress().getValue()` - * [X] Document Details `getDocumentDetails().getValue()` - * [X] ApplicationProfile `.getApplicationProfile()` - * [X] Name `getName().getValue()` - * [X] URL `getUrl().getValue()` - * [X] Logo `getLogo().getValue()` - * [X] Receipt Background Color `getReceiptBgColor().getValue()` +The Yoti SDK can be used for the following products, follow the links for more information about each: +1) [Yoti app integration](/docs/PROFILE.md) - Connect with already-verified customers. +1) [Yoti Doc Scan](/docs/DOCSCAN.md) - Identity verification embedded in your website or app. +1) [Yoti AML](/docs/AML.md) - Anti-Money Laundering check service to allow a deeper KYC process, preventing fraud ## Support @@ -370,3 +99,5 @@ Please provide the following to get you up and working as quickly as possible: * Screenshot Once we have answered your question we may contact you again to discuss Yoti products and services. If you’d prefer us not to do this, please let us know when you e-mail. + +For further documentation, see diff --git a/docs/AML.md b/docs/AML.md new file mode 100644 index 00000000..7f57e50f --- /dev/null +++ b/docs/AML.md @@ -0,0 +1,56 @@ +# AML Integration + +## About + +Yoti provides an AML (Anti Money Laundering) check service to allow a deeper KYC process to prevent fraud. This is a chargeable service, so please contact [sdksupport@yoti.com](mailto:sdksupport@yoti.com) for more information. + +Yoti will provide a boolean result on the following checks: + +* PEP list - Verify against Politically Exposed Persons list +* Fraud list - Verify against US Social Security Administration Fraud (SSN Fraud) list +* Watch list - Verify against watch lists from the Office of Foreign Assets Control + +To use this functionality you must ensure your application is assigned to your Organisation in the Yoti Hub - please see [here](https://developers.yoti.com/yoti-app/web-integration#step-1-creating-an-organisation) for further information. + +For the AML check you will need to provide the following: + +* Data provided by Yoti + * Given name(s) + * Family name + * Postcode/Zip code (US citizens only) - this can be retrieved from the Structured Postal Address attribute + +* Data that must be collected from the user: + * Country of residence (must be an ISO 3166 3-letter code) + * Social Security Number (US citizens only) + +## Consent + +Performing an AML check on a person *requires* their consent. +**You must ensure you have user consent *before* using this service.** + +## Performing a Check + +Given a YotiClient initialised with your SDK ID and KeyPair (see [Client Initialisation](./PROFILE.md#client-initialisation)) performing an AML check is a straightforward case of providing basic profile data. + +```javascript + +// Initiate user profile data. + +const amlAddress = new yoti.AmlAddress('GBR'); +const amlProfile = new yoti.AmlProfile('Edward Richard George', 'Heath', amlAddress); + +yotiClient.performAmlCheck(amlProfile).then((amlResult) => { + console.log(amlResult.isOnPepList); + console.log(amlResult.isOnFraudList); + console.log(amlResult.isOnWatchList); + + // Or + console.log(amlResult); +}).catch((err) => { + console.error(err); +}) +``` + +## Running the example + +- See the [AML Example](../examples/aml-check/README.md) folder for instructions on how to run the AML Example project diff --git a/docs/DOCSCAN.md b/docs/DOCSCAN.md new file mode 100644 index 00000000..3a34d285 --- /dev/null +++ b/docs/DOCSCAN.md @@ -0,0 +1,11 @@ +# Yoti Doc Scan + +## About + +Yoti Doc Scan can be seamlessly integrated with your website, app or custom product so you can perform secure identity checks. You'll be able to request specific ID documents from users directly from your website or app. + +See the the [Developer Docs](https://developers.yoti.com/yoti/getting-started-docscan) for more information. + +## Running the example + +- See the [Doc Scan Example](../examples/doc-scan/README.md) folder for instructions on how to run the Doc Scan Example project diff --git a/docs/PROFILE.md b/docs/PROFILE.md new file mode 100644 index 00000000..754a18d5 --- /dev/null +++ b/docs/PROFILE.md @@ -0,0 +1,194 @@ +NodeJS Yoti App Integration +=========================== + +1) [An Architectural View](#an-architectural-view) - +High level overview of integration + +1) [Client Initialisation](#client-initialisation) - +Description on initialising the client + +1) [Profile Retrieval](#profile-retrieval) - +Description on setting up profile + +1) [Handling Users](#handling-users) - +Description on handling user details + +1) [Running the Example](#running-the-example) +How to run the example project provided + +1) [API Coverage](#api-coverage) - +Attributes defined + +## 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 Hub 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. + +![alt text](login_flow.png "Login flow") + +Yoti also allows you to enable user details verification from your mobile app by means of the [Android](https://github.com/getyoti/android-sdk-button) and [iOS](https://github.com/getyoti/ios-sdk-button) 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. + +## Client Initialisation + +The YotiClient is the SDK entry point. To initialise it you need to include the following snippet inside your endpoint initialisation section: + +```javascript +const yoti = require('yoti'); +const fs = require('fs'); +const CLIENT_SDK_ID = 'YOUR_SDK_ID'; +const PEM = fs.readFileSync('path/to/your-application-pem-file.pem'); +const yotiClient = new yoti.Client(CLIENT_SDK_ID, PEM); +``` + +## 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: + +```javascript + +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: + +```javascript +yotiClient.getActivityDetails(token).then((activityDetails) => { + if(activityDetails.getOutcome() == 'SUCCESS') { + const profile = activityDetails.getProfile(); + } else { + // handle unhappy path + } +}) +``` + +### Programmatic QR code creation + +Dynamic Policy generation is a way of requesting non-static attribute lists for your application. + +This is useful when you want or need different permutations of attributes from Yoti, without having to create a new scenario. + +E.g: + +* Request 1: full-name and date-of-birth +* Request 2: full-name and address + +This service will query Yoti for a QR Code/link associated with the requested attribute list. + +This QR Code/link should then be embedded into your page using the Yoti widget to begin a share with Yoti. + +#### Example + +The following example demonstrates how a Dynamic Policy can be built using attribute methods such as `withFullName()`, and generic method `withWantedAttribute()`. + +```javascript +const wantedEmailAttribute = new yoti.WantedAttributeBuilder() + .withName('email_address') + .withAcceptSelfAsserted() + .build(); + +const dynamicPolicy = new yoti.DynamicPolicyBuilder() + .withFullName() + .withWantedAttribute(wantedEmailAttribute) + .build(); + +const dynamicScenario = new yoti.DynamicScenarioBuilder() + .withCallbackEndpoint('/profile') + .withPolicy(dynamicPolicy) + .build(); + +yotiClient.createShareUrl(dynamicScenario) + .then((shareUrlResult) => { + const shareUrl = shareUrlResult.getShareUrl(); + const refId = shareUrlResult.getRefId(); + }); + +``` + +## Handling Users + +When you retrieve the user profile, you receive a user ID 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 this ID to verify whether (for your application) the retrieved profile identifies a new or an existing user. +Here is an example of how this works: + +```javascript +yotiClient.getActivityDetails(token).then((activityDetails) => { + if(activityDetails.getOutcome() == 'SUCCESS') { + const userProfile = activityDetails.getUserProfile(); // deprecated + const profile = activityDetails.getProfile(); + const user = yourUserSearchFunction(activityDetails.getRememberMeId()); + if(user) { + // handle login + } else { + // handle registration + const givenNames = profile.getGivenNames().getValue(); + const familyName = profile.getFamilyName().getValue(); + } + } else { + // handle unhappy path + } +}) +``` + +Where `yourUserSearchFunction` is a piece of logic in your app that is supposed to find a user, given a _Remember Me ID_. +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 Hub. + +You can retrieve the sources and verifiers for each attribute as follows: + +```javascript +const givenNamesSources = givenNames.getSources(); // list/array of anchors +const givenNamesVerifiers = givenNames.getVerifiers(); // list/array of anchors +const givenNamesAnchors = givenNames.getAnchors(); // list/array of anchors +``` + +You can also retrieve further properties from these respective anchors in the following way: + +```javascript +// Retrieving properties of the first anchor +const type = givenNamesSources[0].getType(); // string +const value = givenNamesSources[0].getValue(); // string +const subtype = givenNamesSources[0].getSubType(); // string +const timestamp = givenNamesSources[0].getSignedTimeStamp().getTimestamp(); // Date object +const originServerCerts = givenNamesSources[0].getOriginServerCerts(); // list of X509 certificates +``` + +## Running the Example + +- See the [Profile Example](../examples/profile/README.md) folder for instructions on how to run the Profile Example project + +## API Coverage + +* Activity Details + * [X] Remember Me ID `getRememberMeId()` + * [X] Parent Remember Me ID `getParentRememberMeId()` + * [X] Receipt ID `getReceiptId()` + * [X] Timestamp `getTimestamp()` + * [X] Base64 Selfie Uri `getBase64SelfieUri()` + * [X] Profile `getProfile()` + * [X] Full Name `getFullName().getValue()` + * [X] Given Names `getGivenNames().getValue()` + * [X] Family Name `getFamilyName().getValue()` + * [X] Age / Date of Birth `getDateOfBirth().getValue()` + * [X] Age / Verify Condition `getAgeVerified().getValue()` + * [X] Gender `getGender().getValue()` + * [X] Nationality `getNationality().getValue()` + * [X] Mobile Number `getPhoneNumber().getValue()` + * [X] Photo `getSelfie().getValue()` + * [X] Email Address `getEmailAddress().getValue()` + * [X] Address `getPostalAddress().getValue()` + * [X] Structured Address `getStructuredPostalAddress().getValue()` + * [X] Document Details `getDocumentDetails().getValue()` + * [X] ApplicationProfile `.getApplicationProfile()` + * [X] Name `getName().getValue()` + * [X] URL `getUrl().getValue()` + * [X] Logo `getLogo().getValue()` + * [X] Receipt Background Color `getReceiptBgColor().getValue()` diff --git a/login_flow.png b/docs/login_flow.png similarity index 100% rename from login_flow.png rename to docs/login_flow.png diff --git a/examples/doc-scan/README.md b/examples/doc-scan/README.md index 3cb00e56..300a3b0d 100644 --- a/examples/doc-scan/README.md +++ b/examples/doc-scan/README.md @@ -6,3 +6,6 @@ 1. Install the dependencies with `npm install` 1. Start the server `npm start` 1. Visit `https://localhost:3000` + +> * The [default controller](./src/controllers/index.controller.js) demonstrates how to create a Doc Scan session +> * The [success controller](./src/controllers/success.controller.js) demonstrates how to retrieve a Doc Scan session