Gigya Job Openings

ID Verification Integration

Skip to end of metadata
Go to start of metadata

Gigya provides integration with a variety of Identity Verification Systems

The following guide describes the best practice integration of an ID verification service into your current Gigya solution.

Overview

Integration with an ID Verification service is based on combining Gigya's user data with calls to the ID verification service, completed with your application’s reaction to the web user’s authenticity score,
as it is returned from the IDV service, to handle in a way fit for your web application.

The integration process is simple and consists of the following steps:

  1. Adding a 'Score' field to your data schema - This step is required for RaaS clients, who's user management is hosted by Gigya, and need to add the appropriate field to contain the user's authentication score.
    Gigya's clients that do not have RaaS should persist the user's score in any way that fits their user management. 
  2. Listening to the 'OnLogin' event - This step should already be implemented in your solution. If not - this is a good chance to do so. The onLogin even alerts you when a user log's in to your system using Gigya's service. The onLogin contains user data, and is a good place to call the ID verification service.
  3. Extracting the user object - The on login response contains the user object from which you can extract user data. Obtain the credentials you need to include in later ID Verification API calls.
  4. Checking for present scores - A user may already have a valid score from passed logins. Checking to see if the user already has a score and the timestamp of that score can save you a great deal of time on unnecessary API calls.
  5. Obtain an IDV score - In case step 4 result showed that the user has no score, or the score has expired already, an API call to an ID Verification service with the user's credentials will provide a fresh score to save to the database.
  6. Saving the score - Once a score is obtained, it is advised to save the score into the user's profile, along with a timestamp to indicate when the score was obtained.
  7. Respond to the user's score - On this step we will run the code to represent our business logic, and react to the user's login attempt based on the score returned from the IDV service. 

 

Examples throughout this guide use RaaS API calls (the 'accounts' namespace) for illustration, although IDS clients can also implement the same functionality, replacing 'accounts' with the 'ids' namespace. For example  - accounts.setSchema becomes ids.setSchema. Clients that do not have RaaS or Identity Access, can also integrate ID verification, however further implementation is needed, as described where necessary. 

 

Integrating ID Verification

For Social Login, the ID verification should be integrated into the Social Login flow, before step #9 - storing the user in you database.

Step 1 - Adding the Client Score to the Gigya Schema (RaaS)

RaaS clients are required to add an additional field (e.g data.idVerify.Score) to the Gigya schema using the accounts.setSchema API call.
By default, the 'writeAcess' parameter is set to 'Server Only' which means it cannot be edited by calls from the client side. It is recommended to leave this parameter as-is to prevent client side scripts to tamper with the user's score, using the accounts.setAccountInfo Web SDK call.

This step is required for RaaS clients only. If you are using Social login alone, you will have no data schema in Gigya, and the 'accounts' namespace will not be available to you. 
Social login clients can skip directly to step 2.

Note: to activate RaaS contact your Gigya Implementation Consultant.

Step 2 - Subscribing to the onLogin Event

When a user logs in to your site using Gigya's social login (via RaaS or the social login plugin), an 'onLogin' event is fired indicating that a user has, well, logged in.
The onLogin event listener receives a response object containing available data on the logged in user, among other things, and allows you commit actions based on that data.
You can register to the onLogin event directly by calling the 'addEventHandler' method (either from socialize or accounts namesapce) and passing it the 'onLogin' parameter:

gigya.accounts.addEventHandlers({onLogin: loginHandler});
Where 'loginHandler' is the function in charge of receiving the user data and transferring it to your application's server to perform the ID verification.

 

var loginHandler = function(response){
    //The response contains information such as the user's UID and other information
    //Send the response to your application's server using Jquery ajax, and handle the user's score as it is returned
    //For example:
    $.ajax({type: 'POST', data: response, success: respondToUserScore});
}

Where 'respondToUserScore' is a function that takes the score and reacts to it accordingly, whether logging out a user with too low of a score, redirecting to the home page, or any other action that complies with your application.

Note: Non-RaaS clients should call the socialize namespace rather than the accounts namespace, which is reserved for RaaS clients. For example - gigya.accounts.addEventHandlers(), should be gigya.socialize.addEventHandlers().
Also note that RaaS's 'profileobject is replaced by a 'user' object when using the 'socialize' namespace. When accessing the user object in step 3, call response['user'] rather than response['profile'].

Step 3 - Extracting the User Object

The response that is passed on to the onLogin event handler contains a profile object that hold the user data associated with the current user.
If the response was passed to the server (as in the example in step 2), obtain the profile object from the response and extract the required fields for your ID Verification service's API.

 

$uid = $_POST['UID'];
//if the response was passed via the POST request
$userObj = $_POST['profile'];
$userEmail = $userObj->email;

Another way is to get the info directly from Gigya (A simple version of sending a request to Gigya):

 

// Define the request with request name and your Gigya API and secret keys
$method = "accounts.getAccountInfo";
$request = new GSRequest($apiKey,$secretKey,$method);

// Set the "uid" parameter to user's ID and send
$request->setParam("uid", $uid);  
$response = $request->send();

// Obtain relevant data from the response
//Check requst result
if($response->getErrorCode()==0)
{    
    //result OK
    $userObj = $response->profile;
    $userEmail = $userObj->email;
}

Note 1: Non-RaaS clients should replace 'accounts.getAccountInfowith 'socialize.getUserInfo', and extract the user object instead of the profile object.
Note 2: The example is written in PHP. For a more details on handling requests, and reference in other languages, refer to the server side SDK documentation.

Step 4 - Is Score Present

Check whether the user already has an (up to date*) ID verification score.

For RaaS clients, the ID verification score will be kept in the user object under the name you selected for in step 1.
Clients who only implement social login have the score kept on their own custom data schema, or not at all.
Once the score is retrieved, it is also advised to examine the creation date of the score, in case it has been a while since calling the ID verification service last. For that it is advised to save a timestamp alongside the score itself.

However, a client can choose to update the score on every login (or even every service call), in which case step 4 is unnecessary and can be skipped. Although you should consider that frequent calls to the IDV can take a lot of time and should not be performed more frequently than required.

If a score is available for the user and valid, you can skip directly to Step 7 and execute appropriate code.

If there is no score for the user, or the score has expired - continue to Step 5 below.

Step 5 - Retrieving the ID Verification Score

To retrieve the ID verification score, load the ID verification services API command with the relevant parameters from the user object, obtained in step 3.
Call the relevant ID verification services API in order to retrieve the score.
Usually the IDV will respond with detailed fields on several aspects of user authentication. Read the service's documentation and obtain the fields that are relevant to your application.

Note: The description of the APIs and services provided by these third-party ID verification services is out of scope of this document and can be found in their relevant documentation.

Step 6 - Storing the Score in Gigya (RaaS)

RaaS clients have added a field for the user's ID score in step 1.
Once we have retrieved the user's score from the ID verification service, we can save it into RaaS using the accounts.setAccountInfo method, or to your own personal data schema.
It is recommended to add a timestamp to the score when saving it to the database, this way you can verify not only the user's score, but also the time that had passed since the user was first issued it, and request for a new one in case it has expired. This can be done by either adding a Time field to your schema (e.g data.idVerify.Time) or appending a timestamp to the score before storing it. Usually, the IDV service will provide a date field along with the score in it's response.

For details, you may refer to the setAccountInfo reference page.

Step 7 - React To User's Score

The last step after obtaining and saving the user's score, is to react to it according to your application's business logic.
For example, if a user's score is below a minimal threshold of authenticity set by you or recommended by your ID verification service, you may want to log the user out immediately and not allow him to perform any further actions on your site as a logged in user. On the other hand, if a user's score is extremely positive, you may want to grant access to a VIP area or reward the user in some way.

This can be done on the client side handler (such as the 'respondToUserScore' function defined in step 2), or on the server side, depending on your applications logic.

Code Example

The following code is a PHP high level example that illustrates a simple implementation of steps 4-7:
Checking for an existing score on the user's profile (without validating it's timestamp), retrieving a score if no score is available, storing it and responding.

 

//Check the field created in step 1 for a value
if ($userObj->{idVerify}->{Score} == null ){
    //if no value, get one by sending a ID Verify API call using the user credentials from step 3
    //If any other parameters are required according to the IDV API, obtain them the same way as the email
    $score = getScoreFromIDVerService($userEmail);

    //Save the score using the 'setAccountInfo' method
    //Normally you should also add a timestamp
    $method = "account.setAccountInfo";
    $request = new GSRequest($apiKey,$secretKey,$method);
    $request->setParam("uid", $uid);
    $request->setParam("data", {idVerify.Score : $score});
    $response = $request->send();
}
else{
    //User object has a score value
    $score = $userObj->{idVerify}->{Score};
}

//Check the score and react
//TOP_SCORE == an upper threshold set by your application logic or recommended by the IDV vendor
//LOW_SCORE == minimal threshold where any score lower is considered a bot or a fake user

if ($score < TOP_SCORE && $score > LOW_SCORE){
    //Score is inconclusive, show a capcha
    header('Location: /showCaptchaPage.php');
} 

if ($score < LOW_SCORE){
    //Score is low, log out the user
    header('Location: /forceLogout.php');
}