Yoti Ruby SDK

Welcome to the Yoti Ruby SDK. This repository contains the tools you need to quickly integrate your Ruby 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 - High level overview of integration
Requirements - Everything you need to get started
Installing the SDK - How to install our SDK
Configuration - Configuring the SDK
Profile Retrieval - How to retrieve a Yoti profile using the token
AML Integration - How to integrate with Yoti's AML (Anti Money Laundering) service
Running the Examples - How to run the example projects provided
API Coverage - Attributes defined
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 your Yoti Dashboard when you create/update your application. It can be found in the Integration section under the Callback URL name.

The image below shows how your application back-end and Yoti integrate into 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

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. Your back-end doesn't need to handle these cases in a significantly different way, but you might decide to handle the User-Agent header in order to provide different responses for desktop and mobile clients.

References

Requirements

The Yoti gem requires at least Ruby 2.0.0. If you're using a version of Ruby lower than 2.2.2 you might encounter issues when Bundler tries to install the Active Support gem. This can be avoided by manually requiring activesupport 4.2.

gem activesupport '~> 4.2'

Versions of Bundler > 1.13 will sort this dependency issue automatically. More info in this comment by André Arko.

Installing the SDK

To import the Yoti SDK inside your project, add this line to your application's Gemfile:

gem 'yoti'

And then execute:

bundle install

Or simply run the following command from your terminal:

[sudo] gem install yoti

SDK Project Import

The gem provides a generator for the initialization file:

rails generate yoti:install

The generated initialisation file can be found in config/initializers/yoti.rb.

Configuration

A minimal Yoti client initialisation looks like this:

Yoti.configure do |config|
  config.client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
  config.key_file_path = ENV['YOTI_KEY_FILE_PATH']
end

Make sure the following environment variables can be accessed by your app:

YOTI_CLIENT_SDK_ID - found on the Key settings page on your application dashboard

YOTI_KEY_FILE_PATH - the full path to your security key downloaded from the Keys settings page (e.g. /Users/developer/access-security.pem)

The following options are available:

Config	Required	Default	Note
`client_sdk_id`	Yes		SDK identifier generated by when you publish your app
`key_file_path`	Yes		Path to the pem file generated when you create your app
`api_url`	No	`https://api.yoti.com`	Path to Yoti URL used for debugging purposes
`api_port`	No	443	Path to Yoti port used for debugging purposes

Keeping your settings and access keys outside your repository is highly recommended. You can use gems like dotenv to manage environment variables more easily.

Deploying to Heroku / AWS Elastic Beanstalk

Although we recommend using a pem file to store your secret key, and take advantage of the UNIX file permissions, your hosting provider might not allow access to the file system outside the deployment process.

If you're using Heroku or other alternative services, you can store the content of the secret key in an environment variable.

Your configuration should look like this:

Yoti.configure do |config|
  config.client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
  config.key = ENV['YOTI_KEY']
end

Where YOTI_KEY is an environment variable with the following format: YOTI_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEp..."

An easier way of setting this on Heroku would be to use the Heroku Command Line

heroku config:add YOTI_KEY ="$(cat your-access-security.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:

yoti_activity_details = Yoti::Client.get_activity_details(params[:token])

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

if yoti_activity_details.outcome == 'SUCCESS'
  user_profile = yoti_activity_details.user_profile
else
  # handle unhappy path
end

The user_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.

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:

if yoti_activity_details.outcome == 'SUCCESS'
  user = your_user_search_function(yoti_activity_details.user_id)

  if user
    # handle login
  else
    # handle registration
  end
else
  # handle unhappy path
end

Where your_user_search_function is a piece of logic in your app that is supposed to find a user, given a user_id. Regardless of whether the user is a new or an existing one, Yoti will always provide their profile, so you don't necessarily need to store it.

AML Integration

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 [email protected] 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 Dashboard - please see here 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 Dashboard)
- 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)

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 Client Initialisation) performing an AML check is a straightforward case of providing basic profile data.

require 'yoti'

Yoti.configure do |config|
  config.client_sdk_id = ENV['YOTI_CLIENT_SDK_ID']
  config.key_file_path = ENV['YOTI_KEY_FILE_PATH']
end

aml_address = Yoti::AmlAddress.new('GBR')
aml_profile = Yoti::AmlProfile.new('Edward Richard George', 'Heath', aml_address)

puts Yoti::Client.aml_check(aml_profile)

Running the Examples

The examples can be found in the examples folder. For them to work you will need a working callback URL that your browser can redirect to. The callback URL for both examples will be: http://your-local-url.domain/profile.

The examples also use the YOTI_APPLICATION_ID environment variable to display the Yoti Connect button. This value can be found in your Yoti account, on the Keys settings page.

Ruby on Rails

rename the .env.example file to .env and fill in the required configuration values
install the dependencies with bundle install
start the server rails server

Visiting the http://your-local-url.domain should show a Yoti Connect button

Sinatra

rename the .env.example file to .env and fill in the required configuration values
install the dependencies with bundle install
start the server ruby ./app.rb