yoti

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 one time use token

6. Handling users - How to manage users

7. Sandbox - How to use the Yoti sandbox service to test your application

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

9. Running the example - Running the profile example project

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 is configured in the Yoti Hub where you create/update your application. For more information on how to create an application please see integration steps.

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.

Requirements

Supported Go Versions:

• 1.11+

Installing the SDK

As of version 2.4.0, modules are used. This means it's not necessary to get a copy or fetch all dependencies as instructed below, as the Go toolchain will fetch them as necessary. You can simply add a require github.com/getyoti/yoti-go-sdk/v2 to go.mod.

To download and install the Yoti SDK and its dependencies, run the following command from your terminal:

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

SDK Project import

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

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

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 Client Identifier generated by Yoti Hub in the Key tab when you create your application.

• path/to/your-application-pem-file.pem is the path to the application pem file. It can be downloaded from the Keys tab in the Yoti Hub.

Please do not open the pem file as this might corrupt the key and you will need regenerate your key.

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

Profile Retrieval

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

activityDetails, errStrings := client.GetActivityDetails(yotiOneTimeUseToken)
if len(errStrings) != 0 {
  // handle unhappy path
}

Profile

You can then get the user profile from the activityDetails struct:

var rememberMeID string = activityDetails.RememberMeID()
var parentRememberMeID string = activityDetails.ParentRememberMeID()
var userProfile yoti.Profile = activityDetails.UserProfile

var selfie = userProfile.Selfie().Value()
var givenNames string = userProfile.GivenNames().Value()
var familyName string = userProfile.FamilyName().Value()
var fullName string = userProfile.FullName().Value()
var mobileNumber string = userProfile.MobileNumber().Value()
var emailAddress string = userProfile.EmailAddress().Value()
var address string = userProfile.Address().Value()
var gender string = userProfile.Gender().Value()
var nationality string = userProfile.Nationality().Value()
var dateOfBirth *time.Time
dobAttr, err := userProfile.DateOfBirth()
if err != nil {
    // handle error
} else {
    dateOfBirth = dobAttr.Value()
}
var structuredPostalAddress map[string]interface{}
structuredPostalAddressAttribute, err := userProfile.StructuredPostalAddress()
if err != nil {
    // handle error
} else {
    structuredPostalAddress := structuredPostalAddressAttribute.Value().(map[string]interface{})
}

If you have chosen Verify Condition on the Yoti Hub with the age condition of "Over 18", you can retrieve the user information with the generic .GetAttribute method, which requires the result to be cast to the original type:

userProfile.GetAttribute("age_over:18").Value().(string)

GetAttribute returns an interface, the value can be acquired through a type assertion.

Anchors, Sources and Verifiers

An Anchor represents how a given Attribute has been sourced or verified. These values are created and signed whenever a Profile Attribute is created, or verified with an external party.

For example, an attribute value that was sourced from a Passport might have the following values:

Similarly, an attribute verified against the data held by an external party will have an Anchor of type VERIFIER, naming the party that verified it.

From each attribute you can retrieve the Anchors, and subsets Sources and Verifiers (all as []*anchor.Anchor) as follows:

givenNamesAnchors := userProfile.GivenNames().Anchors()
givenNamesSources := userProfile.GivenNames().Sources()
givenNamesVerifiers := userProfile.GivenNames().Verifiers()

You can also retrieve further properties from these respective anchors in the following way:

var givenNamesFirstAnchor *anchor.Anchor = givenNamesAnchors[0]

var anchorType anchor.Type = givenNamesFirstAnchor.Type()
var signedTimestamp *time.Time = givenNamesFirstAnchor.SignedTimestamp().Timestamp()
var subType string = givenNamesFirstAnchor.SubType()
var value []string = givenNamesFirstAnchor.Value()

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:

activityDetails, err := client.GetActivityDetails(yotiOneTimeUseToken)
if err == nil {
    user := YourUserSearchFunction(activityDetails.RememberMeID())
    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 RememberMeID. 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.

Sandbox

See examples/profilesandbox for information about how to use the Yoti Profile Sandbox service.

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 Hub - 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 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 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.

• Rename the .env.example file to .env and fill in the required configuration values (mentioned in the Configuration section)
• Change directory to the aml example folder: cd examples/aml
• Install the dependencies with go get
• Start the example with go run main.go

Running the Profile Example

The profile retrieval example can be found in the examples folder.

• Change directory to the profile example folder: cd examples/profile
• On the Yoti Hub:
  • Set the application domain of your app to localhost:8080
  • Set the scenario callback URL to /profile
• Rename the .env.example file to .env and fill in the required configuration values (mentioned in the Configuration section)
• Install the dependencies with go get
• Start the server with go run main.go certificatehelper.go

Visiting https://localhost:8080/ should show a Yoti Connect button

API Coverage

• Activity Details
  • Remember Me ID RememberMeID()
  • Parent Remember Me ID ParentRememberMeID()
  • User Profile UserProfile
    • Selfie Selfie()
    • Selfie Base64 URL Selfie().Value().Base64URL()
    • Given Names GivenNames()
    • Family Name FamilyName()
    • Full Name FullName()
    • Mobile Number MobileNumber()
    • Email Address EmailAddress()
    • Date of Birth DateOfBirth()
    • Postal Address Address()
    • Structured Postal Address StructuredPostalAddress()
    • 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