README.md in yoti-1.1.0 vs README.md in yoti-1.2.0

- old
+ new

@@ -2,58 +2,30 @@ 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. ## Table of Contents -1) [An Architectural view](#an-architectural-view) - -High level overview of integration +1. [An Architectural view](#an-architectural-view) - High level overview of integration +1. [Requirements](#requirements) - Everything you need to get started +1. [Installing the SDK](#installing-the-sdk) - How to install our SDK +1. [Configuration](#configuration) - Configuring the SDK +1. [Profile Retrieval](#profile-retrieval) - How to retrieve a Yoti profile using the token +1. [AML Integration](#aml-integration) - How to integrate with Yoti's AML (Anti Money Laundering) service +1. [Running the Examples](#running-the-examples) - How to run the example projects provided +1. [API Coverage](#api-coverage) - Attributes defined +1. [Support](#support) - Please feel free to reach out -2) [References](#references)- -Guides before you start - -3) [Requirements](#requirements)- -Everything you need to get started - -4) [Installing the SDK](#installing-the-sdk)- -How to install our SDK - -5) [SDK Project import](#sdk-project-import)- -How to install the SDK to your project - -6) [Configuration](#configuration)- -entry point explanation - -7) [Profile Retrieval](#profile-retrieval)- -How to retrieve a Yoti profile using the token - -8) [Handling users](#handling-users)- -How to manage users - -9) [API Coverage](#api-coverage)- -Attributes defined - -10) [Running the examples](running-the-examples)- -Attributes defined - -11) [Support](#support)- -Please feel free to reach out - -12) [Change Log](#change-log) - -13) [License](#license) - ## 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](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. 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 * [AES-256 symmetric encryption][] @@ -90,25 +62,25 @@ ``` And then execute: ```shell -$ bundle install +bundle install ``` Or simply run the following command from your terminal: ```shell -$ [sudo] gem install yoti +[sudo] gem install yoti ``` -## SDK Project import +## SDK Project Import The gem provides a generator for the initialization file: ```shell -$ rails generate yoti:install +rails generate yoti:install ``` The generated initialisation file can be found in `config/initializers/yoti.rb`. ## Configuration @@ -119,24 +91,25 @@ 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 +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. [dotenv]: https://github.com/bkeepers/dotenv @@ -153,28 +126,22 @@ 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: +Where `YOTI_KEY` is an environment variable with the following format: `YOTI_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEp..."` -``` -YOTI_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEp..." -``` - An easier way of setting this on Heroku would be to use the [Heroku Command Line][] ```shell heroku config:add YOTI_KEY ="$(cat your-access-security.pem)" ``` [Heroku Command Line]: https://devcenter.heroku.com/articles/heroku-command-line +## Profile Retrieval - -## 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: ```ruby yoti_activity_details = Yoti::Client.get_activity_details(params[:token]) ``` @@ -187,15 +154,18 @@ 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. +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 +### 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 them 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: +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: ```ruby if yoti_activity_details.outcome == 'SUCCESS' user = your_user_search_function(yoti_activity_details.user_id) @@ -207,14 +177,59 @@ 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 wether the user is a new or an existing one, Yoti will always provide their profile, so you don't necessarily need to store it. +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. -## Running the examples +## 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 [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 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) + +### 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 [Client Initialisation](#client-initialisation)) performing an AML check is a straightforward case of providing basic profile data. + +```ruby +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](examples). 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. @@ -228,45 +243,44 @@ ### Sinatra * rename the [.env.default](examples/sinatra/.env.default) file to `.env` and fill in the required configuration values * install the dependencies with `bundle install` -* start the server `dotenv ./app.rb` +* start the server `ruby ./app.rb` Visiting the `http://your-local-url.domain` should show a Yoti Connect button -## API coverage +### AML Check +* rename the [.env.default](examples/aml_check/.env.default) file to `.env` and fill in the required configuration values +* install the dependencies with `bundle install` +* run the script with `ruby ./app.rb` + +## API Coverage + * Activity Details - * [X] User ID `user_id` - * [X] Profile - * [X] Selfie `selfie` - * [X] Given Names `given_names` - * [X] Family Name `family_name` - * [X] Mobile Number `phone_number` - * [X] Email address `email_address` - * [X] Date of Birth `date_of_birth` - * [X] Address `postal_address` - * [X] Gender `gender` - * [X] Nationality `nationality` - * [X] Base64 Selfie URI `base64_selfie_uri` + * [X] User ID `user_id` + * [X] Profile + * [X] Selfie `selfie` + * [X] Full Name `full_name` + * [X] Given Names `given_names` + * [X] Family Name `family_name` + * [X] Mobile Number `phone_number` + * [X] Email Address `email_address` + * [X] Age / Date of Birth `date_of_birth` + * [X] Age / Verify Condition `age_[over|under]:[1-999]` + * [X] Address `postal_address` + * [X] Gender `gender` + * [X] Nationality `nationality` + * [X] Base64 Selfie URI `base64_selfie_uri` ## Support For any questions or support please email [sdksupport@yoti.com](mailto:sdksupport@yoti.com). -Please provide the following the get you up and working as quick as possible: +Please provide the following to get you up and working as quickly as possible: -- Computer Type -- OS Version -- Version of Ruby being used -- Screenshot +* Computer type +* OS version +* Version of Ruby being used +* Screenshot - -## Changelog - -See recent changes in the [release notes][release notes] or the [changelog](CHANGELOG.md). - -[release notes]: https://github.com/getyoti/yoti-ruby-sdk/releases - -## License - -The gem is available under the following [terms](LICENSE.txt). +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.