yoti

README

Yoti Go SDK

Welcome to the Yoti Go SDK. This repo contains the tools and step by step instructions you need to quickly integrate your Go 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 - High level overview of integration

2. Installing the SDK - How to install our SDK

3. SDK Project import - How to install the SDK to your project

4. Configuration - How to initialise your configuration

5. Profile Retrieval - How to retrieve a Yoti profile using the token

6. Handling users - How to manage users

7. AML Integration - How to integrate with Yoti's AML (Anti Money Laundering) service

8. Running the tests - Attributes defined

9. Running the example - Attributes defined

10. API Coverage - Attributes defined

11. Support - Please feel free to reach out

12. References

An Architectural View

Before you start your integration, here is a bit of background on how the integration works. 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 the Yoti Dashboard when you create/update your application. For more information on how to create an application please check our developer page.

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.

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. You might just decide to handle the User-Agent header in order to provide different responses for desktop and mobile clients.

Installing the SDK

To import the Yoti SDK inside your project, simply run the following command from your terminal:

go get "github.com/getyoti/yoti-go-sdk"

SDK Project import

You can reference the project URL by adding the following import:

import "github.com/getyoti/yoti-go-sdk"

Configuration

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

sdkID := "your-sdk-id";
key, err := ioutil.ReadFile("path/to/your-application-pem-file.pem")
if err != nil {
    // handle key load error
}

client := yoti.Client{
    SdkID: sdkID,
    Key: key}

Where:

• sdkID is the SDK identifier generated by Yoti Dashboard 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 Dashboard.

Please do not open the pem file as this might corrupt the key and you will need to create a new application.

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

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:

profile, err := client.GetUserProfile(yotiToken)

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

profile, err := client.GetUserProfile(yotiToken)
if err != nil {
  // handle unhappy path
}

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:

profile, err := client.GetUserProfile(yotiToken)
if err == nil {
    user := YourUserSearchFunction(profile.ID)
    if user != nil {
        // 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 the Tests

You can run the unit tests for this project by executing the following command inside the repository folder

go test

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

givenNames := "Edward Richard George"
familyName := "Heath"

amlAddress := yoti.AmlAddress{
    Country: "GBR"}

amlProfile := yoti.AmlProfile{
    GivenNames: givenNames,
    FamilyName: familyName,
    Address:    amlAddress}

result, err := client.PerformAmlCheck(amlProfile)

log.Printf(
    "AML Result for %s %s:",
    givenNames,
    familyName)
log.Printf(
    "On PEP list: %s",
    strconv.FormatBool(result.OnPEPList))
log.Printf(
    "On Fraud list: %s",
    strconv.FormatBool(result.OnFraudList))
log.Printf(
    "On Watch list: %s",
    strconv.FormatBool(result.OnWatchList))
}

Additionally, an example AML application is provided in the examples folder. As with the other example project, you'll need to rename .env.example to .env and fill in the variables within the file.

Running the Profile Example

The profile retrieval example 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 will be: http://your-local-url:8080/profile.

The examples also uses 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.

• rename the .env.example file to .env and fill in the required configuration values
• install the dependencies with go get
• start the server go run main.go

API Coverage

• Activity Details
  • Profile
    • User ID ID
    • Selfie Selfie
    • Selfie URL Selfie.URL
    • Given Names GivenNames
    • Family Name FamilyName
    • Full Name FullName
    • Mobile Number MobileNumber
    • Email Address EmailAddress
    • Age / Date of Birth DateOfBirth
    • Age / Verify Condition age_[over|under]:[1-999]
    • Postal Address Address
    • Gender Gender
    • Nationality Nationality

Support

For any questions or support please email sdksupport@yoti.com. Please provide the following to get you up and working as quickly as possible:

• Computer type
• OS version
• Version of Go being used
• 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.

References

• AES-256 symmetric encryption
• RSA pkcs asymmetric encryption
• Protocol buffers
• Base64 data

Documentation

Index

• Constants
• Variables
• type AmlAddress
• type AmlProfile
• type AmlResult
  • func GetAmlResultFromResponse(amlResponse []byte) AmlResult
• type AttributeType
• type AttributeValue
  • func (val AttributeValue) GetContentType() (result string)
• type Client
  • func (client *Client) GetUserProfile(token string) (UserProfile, error)
  • func (client *Client) PerformAmlCheck(amlProfile AmlProfile) (AmlResult, error)
• type Image
  • func (image *Image) GetContentType() string
  • func (image *Image) URL() string
• type ImageType
• type UserProfile

Constants

const (
	//HTTPMethodPost Post HTTP method
	HTTPMethodPost = "POST"
	//HTTPMethodGet Get HTTP method
	HTTPMethodGet = "GET"
	//HTTPMethodPut Put HTTP method
	HTTPMethodPut = "PUT"
	//HTTPMethodPatch Patch HTTP method
	HTTPMethodPatch = "PATCH"
)

Variables

var (
	//ErrProfileNotFound profile was not found during activity retrieval for the provided token
	ErrProfileNotFound = errors.New("ProfileNotFound")
	//ErrFailure there was a failure during activity retrieval
	ErrFailure = errors.New("Failure")
	//ErrSharingFailure there was a failure when sharing
	ErrSharingFailure = errors.New("SharingFailure")
)

Types

type AmlAddress

type AmlAddress struct {
	Country  string `json:"country"`
	Postcode string `json:"post_code"`
}

AmlAddress Address for Anti Money Laundering (AML) purposes

type AmlProfile

type AmlProfile struct {
	GivenNames string     `json:"given_names"`
	FamilyName string     `json:"family_name"`
	Address    AmlAddress `json:"address"`
	SSN        string     `json:"ssn"`
}

AmlProfile User profile for Anti Money Laundering (AML) checks

type AmlResult

type AmlResult struct {
	OnFraudList bool `json:"on_fraud_list"`
	OnPEPList   bool `json:"on_pep_list"`
	OnWatchList bool `json:"on_watch_list"`
}

AmlResult Result of Anti Money Laundering (AML) check for a particular user

func GetAmlResultFromResponse

func GetAmlResultFromResponse(amlResponse []byte) AmlResult

GetAmlResultFromResponse Parses AML result from response

type AttributeType

type AttributeType int

AttributeType format of the attribute

const (
	//AttributeTypeDate date format
	AttributeTypeDate AttributeType = 1 + iota
	//AttributeTypeText text format
	AttributeTypeText
	//AttributeTypeJpeg JPEG format
	AttributeTypeJpeg
	//AttributeTypePng PNG fornmat
	AttributeTypePng
)

type AttributeValue

type AttributeValue struct {
	// Type represents the format of the piece of user data, whether it is a date, a piece of text or a picture
	//
	// Note the potential values for this variable are stored in constants with names beginning with
	// 'AttributeType'. These include:
	// 	yoti.AttributeTypeDate
	// 	yoti.AttributeTypeText
	// 	yoti.AttributeTypeJpeg
	// 	yoti.AttributeTypePng
	Type  AttributeType
	Value []byte
}

AttributeValue represents a small piece of information about a Yoti user such as a photo of the user or the user's date of birth.

func (AttributeValue) GetContentType

func (val AttributeValue) GetContentType() (result string)

GetContentType returns the MIME type of this piece of Yoti user information. For more information see: https://en.wikipedia.org/wiki/Media_type

type Client

type Client struct {
	// SdkID represents the SDK ID and NOT the App ID. This can be found in the integration section of your
	// application dashboard at https://www.yoti.com/dashboard/
	SdkID string

	// Key should be the security key given to you by yoti (see: security keys section of
	// https://www.yoti.com/dashboard/) for more information about how to load your key from a file see:
	// https://github.com/getyoti/yoti-go-sdk/blob/master/README.md
	Key []byte
}

Client represents a client that can communicate with yoti and return information about Yoti users.

func (*Client) GetUserProfile

func (client *Client) GetUserProfile(token string) (UserProfile, error)

GetUserProfile requests information about a Yoti user using the token generated by the Yoti login process. It returns the outcome of the request. If the request was successful it will include the users details, otherwise it will specify a reason the request failed.

func (*Client) PerformAmlCheck

func (client *Client) PerformAmlCheck(amlProfile AmlProfile) (AmlResult, error)

PerformAmlCheck performs an Anti Money Laundering Check (AML) for a particular user. Returns three boolean values: 'OnPEPList', 'OnWatchList' and 'OnFraudList'.

type Image

type Image struct {
	Type ImageType
	Data []byte
}

Image format of the image and the image data

func (*Image) GetContentType

func (image *Image) GetContentType() string

GetContentType returns the MIME type of this piece of Yoti user information. For more information see: https://en.wikipedia.org/wiki/Media_type

func (*Image) URL

func (image *Image) URL() string

URL Image encoded in a base64 URL

type ImageType

type ImageType int

ImageType Image format

const (
	//ImageTypeJpeg JPEG format
	ImageTypeJpeg ImageType = 1 + iota
	//ImageTypePng PNG format
	ImageTypePng
)

type UserProfile

type UserProfile struct {
	// ID is a unique identifier Yoti assigns to your user, but only for your app
	// if the same user logs into your app again, you get the same id
	// if she/he logs into another application, Yoti will assign a different id for that app
	ID string

	// Selfie is a photograph of the user. This will be nil if not provided by Yoti
	Selfie *Image

	// GivenNames represents the user's given names. This will be an empty string if not provided by Yoti
	GivenNames string

	// Family represents the user's family name. This will be an empty string if not provided by Yoti
	FamilyName string

	// Full name represents the user's full name. This will be an empty string if not provided by Yoti
	FullName string

	// MobileNumber represents the user's mobile phone number. This will be an empty string if not provided by Yoti
	MobileNumber string

	// EmailAddress represents the user's email address. This will be an empty string if not provided by Yoti
	EmailAddress string

	// DateOfBirth represents the user's date of birth. This will be nil if not provided by Yoti
	DateOfBirth *time.Time

	// Address represents the user's address. This will be an empty string if not provided by Yoti
	Address string

	// Gender represents the user's gender. This will be an empty string if not provided by Yoti
	Gender string

	// Nationality represents the user's nationality. This will be an empty string if not provided by Yoti
	Nationality string

	// OtherAttributes is a map of any other information about the user provided by Yoti. The key will be the name
	// of the piece of information, and the keys associated value will be the piece of information itself.
	OtherAttributes map[string]AttributeValue
}

UserProfile represents the details retrieved for a particular