Skip to content

Latest commit

 

History

History
140 lines (110 loc) · 5.48 KB

PROFILE.md

File metadata and controls

140 lines (110 loc) · 5.48 KB
Raw

Ruby Yoti App Integration

  1. An Architectural View - High level overview of integration

  2. Profile Retrieval - Description on setting up profile

  3. Handling Users - Description on handling user details

  4. Running the Examples How to run the example project provided

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

Yoti also allows you to enable user details verification from your mobile app by means of the Android and iOS 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.

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 user profile:

one_time_use_token = params[:token]
yoti_activity_details = Yoti::Client.get_activity_details(one_time_use_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'
  profile = yoti_activity_details.profile
  given_names = profile.given_names.value
  family_name = profile.family_name.value
else
  # handle unhappy path
end

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.

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)
  profile = yoti_activity_details.profile

  if user
    # handle login
    email = profile.email_address.value
  else
    # handle registration
    given_names = profile.given_names.value
    family_name = profile.family_name.value
    email = profile.email_address.value
  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.

You can retrieve the sources and verifiers for each attribute as follows:

given_names_sources = profile.given_names.sources # list of anchors
given_names_verifiers = profile.given_names.verifiers # list of anchors
given_names_anchors = profile.given_names.anchors # list of anchors

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

# Retrieving properties of the first anchor
type = given_names_sources[0].type # string
value = given_names_sources[0].value # string
sub_type = given_names_sources[0].sub_type # string
time_stamp = given_names_sources[0].signed_time_stamp.time_stamp # DateTime object
origin_server_certs = given_names_sources[0].origin_server_certs # list of X509 certificates

In case you want to prove the sources and verifiers of the helperActivityDetails.age_verified on Age Over 18 set as age derivation, please retrieve it's original attribute from the profile as follow:

age_attribute = profile.get_attribute('age_over:18')
sources = age_attribute.sources
verifiers = age_attribute.verifiers
anchors = age_attribute.anchors

Running the Examples

Follow the below links for instructions on how to run the example projects:

API Coverage

  • Activity Details
    • Remember Me ID remember_me_id
    • Parent Remember Me ID parent_remember_me_id
    • Receipt ID receipt_id
    • Timestamp timestamp
    • Base64 Selfie URI base64_selfie_uri
    • Age verified age_verified
    • Profile profile
      • Selfie selfie
      • Full Name full_name
      • Given Names given_names
      • Family Name family_name
      • Mobile Number phone_number
      • Email Address email_address
      • Age / Date of Birth date_of_birth
      • Address postal_address
      • Structured Postal Address structured_postal_address
      • Gender gender
      • Nationality nationality
    • Application Profile application_profile
      • Name name
      • URL url
      • Logo logo
      • Receipt Background Color receipt_bgcolor