Issuer uSDK v6.6 (beta)

The Issuer uSDK 6.6 for Browser is a javascript library that helps issuers (ACSes, etc) to perform various advanced actions during 3DS Method and/or 3DS Challenge flow. For instance an issuer can instruct the uSDK to save a device ID/tag (sort of a cookie) during 3DS Method and then read the tag during consequent transactions.

Overview

The instructions

An instruction is an action that an issuer prescribes the uSDK to perform (and return a result) during the next 3DS transaction. Typically the uSDK persists instructions received in transaction A (either during 3DS Method or a Challenge Flow) so they can be executed and their results obtained during transaction B.

The following instructions are currently supported:

Storing the instruction(s)

An issuer is supposed to form a special javascript object which contains one or more instruction and pass it to storeInstructions API method the uSDK exposes. The uSDK persists the instructions in the user’s browser so that the data lives through browser restarts. The data format for the instructions is shown below:

{
  "name": "com.msignia.usdk",
  "id": "com.msignia.usdk",
  "criticalityIndicator": false,
  "data": {
    "DeviceID": { "v": 1, "value": "18d7c8" },
    "GetDeviceAttributes": { "v": 1 },
    "CaptureBehavioralBiometrics": { "v": 1 },
  }
}

In the example above there’re three instructions passed - DeviceID, GetDeviceAttributes and CaptureBehavioralBiometrics. Up on receiving such a set of instructions the uSDK stores them internally but does not execute any of them just yet. It needs to be told to execute the stored instructions as shown in the next section.

There’s usdk.storeInstructions(instructions) method the uSDK has for the purpose, it is documented further in this document.

Executing the instructions

The uSDK exposes two ways of executing stored instructions. The first one is an instant one - it executes the instructions and returns the results of the executiion:

usdk.executeInstructions()
  .then(executionResult => {
    console.log("Received: ", executionResult);
});

The second way should be employed when one or more instruction stored previously were supposed to capture user interaction. The challenge flow is a good example of this case - one would want the uSDK to start capturing behavioral biometrics right before user begins to type an answer in the text field and finish capturing when the user finishes doing that by clicking a SUBMIT button:

// tells the uSDK to begin executing CaptureBehavioralBiometrics thus capruting typings/mouse events
usdk.startExecutingInstructions({});  

// enable the challenge form so that user can start interacting with it
challengeForm.enabled = true; // this is a schematic code

function submitChallenge() {
  usdk.finishExecutingInstructions()
    .then(executionResult => {
      console.log("Received: ", executionResult);
    });
}

As shown above, the two methods - startExecutingInstructions and finishExecutingInstructions need to be called in order.

The example shows the results of the two instructions - DeviceID and CaptureBehavioralBiometrics executed by the uSDK. Each of the instructions defines its own result format. See the documentation for each of the instructions further in this document.

Integrating the uSDK

Since the issuer uSDK is still in beta one has to contact an mSIGNIA administrator to obtain it. Normally it is shipped as a single javascript file which is refered to as usdk.js further in the document.

mSIGNIA administrator will provide the customer with a license key for the uSDK. The license key should be passed to the uSDK at initialization time as shown later in this document.

Once the file is obtained, it has to be included in a web page like the following:

<script src="https://some-issuer-backend.com/usdk.js"></script>

The an instance of uSDK is recommended to be created like this:

const usdk = new Usdk({
  licenseKey: "<the license key issued by the administrator>",
  logLevel: "INFO", // DEBUG | INFO | WARN | ERROR
});

And finally the uSDK should be initialized:

Then it has to be initialized:

usdk.initialize().then(() => {
  console.log("uSDK initialized successfully!");
}).catch((error) => {
  console.log("uSDK failed to initialize, error: ", error);
});

Executing uSDK methods

Store instructions

The storeInstructions is used when ab issuer wants the uSDK to store one or more instructions. Once an instruction is stored, the uSDK will be able to execute it within the same or future transaction.

usdk.storeInstructions(instructions);

The instructions argument can be one of the following:

1. A base64 encoded string that once decoded and JSON parsed will yield a javascript object documented in the Storing the instruction(s) in the beginning of this document
2. A javascript object as per Storing the instruction(s) in the beginning of this document

The method does not return any result, it is void thus.

Execute instructions

As it’s been explained in the Overview - Executing the instructions, there are two possible ways running the instructions - an instant one and a continuous one. When one of the two ways are called, the uSDK recalls all stored instructions and executes them. The result of their execution is then compiled and returned back to the caller.

An instant execution

usdk.executeInstructions()
  .then(executionResult => {
    console.log("Received: ", executionResult);
});

This will cause the uSDK to execute all instructions it has previously stored, combine their results into a resulting object and return it back.

A continuous execution

usdk.startExecutingInstructions({});  

// then after some time or up on certain event:
usdk.finishExecutingInstructions()
  .then(executionResult => {
    console.log("Received: ", executionResult);
});

The result

The execution result is an object whose keys are the instruction names the SDK has executed and the values are the values those instructions captured/resulted with. Here’s an example:

{
    "CaptureBehavioralBiometrics": { "v": 1, "data": "[\"mm\",87,328,461],[\"mm\",103,318,467]..." },
    "DeviceID": { "v": 1, "data": "ce2a86" }
}

Instructions reference

DeviceID Instruction

Using the DeviceID instruction an issuer can tell uSDK to store certain indentifier in the user’s browser and return it back when executeInstructions is called during a consequent transaction.

Store

So, to store such an instruction, the following object needs to be passed to uSDK’s storeInstruction method:

{
  "name": "com.msignia.usdk",
  "id": "com.msignia.usdk",
  "criticalityIndicator": false,
  "data": {
    "DeviceID": { "v": 1, "value": "18d7c8" },
  }
}

In the example above, the uSDK will store the value of 18d7c8 in the user’s browser.

Execute

When executed using either instant or continuous routine, the following result is returned:

{
    "DeviceID": { "v": 1, "data": "18d7c8" }
}

GetDeviceAttributes Instruction

The executing result executing of the GetDeviceAttributes instruction is a set of browser device fingerprinting attributes as per 3DS 2.2 specification.

Store

{
  "name": "com.msignia.usdk",
  "id": "com.msignia.usdk",
  "criticalityIndicator": false,
  "data": {
    "GetDeviceAttributes": { "v": 1 },
  }
}

Note, there’s no arguments except of the version (v) in the object.

Execute

The execution result is then looks like the following:

{
    "GetDeviceAttributes": { "v": 1, 
      "data": { 
        "browserColorDepth": "24", 
        "browserScreenWidth": "2400",
        // other attributes go below...
      } 
    }
}

CaptureBehavioralBiometrics Instruction

This instruction tells uSDK to capture behavioral biometric while user interacts with the UI. This instruction should only be executed using the continous flow - startExecutingInstructions and then after a while the finishExecutingInstructions - because it takes a while while the user interacts so the uSDK needs to exactly know when to start executing and when to finish that.

Store

{
  "name": "com.msignia.usdk",
  "id": "com.msignia.usdk",
  "criticalityIndicator": false,
  "data": {
    "CaptureBehavioralBiometrics": { "v": 1 },
  }
}

Execute

{
    "CaptureBehavioralBiometrics": { "v": 1, "data": "ptypes:{mouse:130},k229:0,kn:0,tz:-180,pr:2,u..." }
}

Sample Issuer Apps

There’re two sample backends implemented and exposed to help an issuer to grasp the concepts easier. The one is a sample backend that shows what an ACS backend would need to do in order to integrate and leverage the issuer uSDK. The other one is a sample merchant backend that shows how it is recommended to maintain the 3DS Method as well as Challenge iFrames as well as how to implement the notification callbacks.

• Sample ACS backend: https://qa-issuer-sample-acs.msignia.com
• Sample Merchant backend: https://qa-issuer-sample-merchant.msignia.net

The backends are configured to talk each to the other. Per request, mSIGNIA may provide the source codes of the backends.