Overview

Adaptive Multi-Factor Authentication provides the ability to dynamically analyse user requests for corporate information and apply business security policy to application access to minimize the risk of improper data exposure or loss.

Adaptive Multi-Factor Authentication uses both device fingerprints and behavioral data to come up with a risk score, based on which you either permit or deny access. This risk score would become a second factor in authentication, the first factor being passwords or any another "normal" authentication. The risk score can also be used to determine if further information is needed from the end user to complete the transaction.

Pre-requisites

  • You need to create a free trial account with miniOrange.
  • Contact us for registering you domain with miniOrange.You can email us at info@xecurify.com.
  • Contact us for requesting miniOrange Adaptive Multi-Factor Authentication API Package.You can email us at info@xecurify.com.

Steps to integrate miniOrange Adaptive Multi-Factor Authentication API

Step 1: Import miniOrange JS/SWF files in your web page

Part A: miniOrange Adaptive Multi-Factor Authentication API package contains various JS (Javascript) files that you will need to import in your web pages from where you like to call miniOrange APIs.

Part B: There are 4 Adaptive Multi-Factor Authentication APIs that you need to call (The Javascript files that you included makes these calls):

Is User Registered API

checks whether the user is registered with the miniOrange or not.

You don't have to worry about maintaining whether your user is registered with miniOrange or not during the initial roll-out of Adaptive Multi-Factor Authentication product to your user. You just have to make a call to this API to find out if the currently logged in user is registered with us or not. You will need the following user's information to call this API:

Attributes Description
CustomerKey Customer ID provided to you. (Mandatory)
Email Email ID of the user. (Mandatory)

Step 1: Import miniOrange JS/SWF files in your web page

You will need to include 5 JS files (provided in the package) in your web page: client.js, swfobject.js, fontdetect.js, ua-parser.js, miniorange-fp.js. Also you will need to copy other SWF files (provided in the package) to the js folder of your web application.

  • Create a directory named "js" inside the folder which contains your web page (the page where you will be including the JS files.
  • Copy all the JS and SWF files under this js directory.
  • Import all the JS file in your web page. For eg.
<html>
  <head>
    <title>ABC Inc.</title>
  </head>
  <body>
    <!--   Your content here  -->

    <script src="js/client.js"></script>
    <script src="js/swfobject.js"></script>
    <script src="js/fontdetect.js"></script>
    <script src="js/ua-parser.js"></script>
    <script src="js/murmurhash3.js"></script>
    <script src="js/miniorange-fp.js"></script>
  </body>
</html>

NOTE: Notice that all the JS file included at the end of the webpage and the order in which they are included.

Step 2: Calling miniOrange Is User Registered API

Once you have includes JS files in your register-user web page and copied all other files to your js folder, you will need to make a Javascript call like this:

/* fp.isUserRegistered() : Javascript function for checking if user is registered or not. */
fp.isUserRegistered(customerKey, userKey, mSuccess, mError);

Request Attributes

Attributes Data Type Description
customerKey String Customer ID provided to you.(Mandatory)
userKey String Email ID of the user you want to check.(Mandatory)
mSuccess Javascript function Javascript function where you want to receive a response if the request is successful.(Mandatory)
mError Javascript function Javascript function where you want to receive response if the request has failed.(Mandatory)

Response

Attributes Data Type Description
customerKey String Customer ID you sent in the request.
userKey String The username (email) you sent in the request
status String Overall status of the request (USER_REGISTERED / USER_NOT_REGISTERED / ERROR)
message String Additional message related to status.

Example and Code Snippet

Collect details like phone number, alternate email, security question/answer from your verified user and call miniOrange Register User API along with these details.

      function register() {
      /* Get your customerKey */
      var customerKey = '<YOUR_CUSTOMER_KEY>';

      /* Get the username (email) of the user */
      var username = 'demo@gmail.com';

      /* Get the User's Alternate Email of the user */
      var alternateEmail = 'alternate.email@gmail.com';

      /* Get the User's Phone number of the user */
      var phoneNumber = '+19xxxxxxxxx';

      /* Get the questions & answers selected by the user */
      var question1 = 'What is your favourite color?';
      var answer1 = 'red';

      var question2 = 'What is you frequent flyer number?';
      var answer2 = 'FL12548';

      /* Create the KBA Question/Answer array list */
      var kbaAnswers = [];

      /* Add Question 1 to the list */
      kbaAnswers.push({
        "question":question1,
        "answer":answer1
      });

      /* Add Question 2 to the list */
      kbaAnswers.push({
        "question":question2,
        "answer":answer2
      });

      /* Define the onSuccess function */
      var onRegisterSuccess = function(result) {
        /* Handle the Successful registration */
        console.log("Registration successful, Status: " + result.status);
      }

      /* Define the onError function */
      var onRegisterError = function(result) {
        /* Handle the registration error */
        console.log("Status: "+result.status + ", Reason: " + result.message);
      }

      /* Call Register User API */
      fp.registerUser(customerKey, username, phoneNumber, alternateEmail, kbaAnswers, onRegisterSuccess,
          onRegisterError);
     }

Register User API

registers your users with miniOrange (can be used in the initial roll-out to users)

You will need the following user's information to register your users with miniOrange:

Attributes Description
CustomerKey Customer ID provided to you. (Mandatory)
Email Email ID of the user (Mandatory)
First Name First name of the user (Optional)
Last Name Last name of the user (Optional)
Phone Number Phone number of the user (Optional)
Alternate Email Alternate email provided by the user (Optional)
Security Question/Answer List of Security Questions & Answers provided by the user (Mandatory)

Step 1: Import miniOrange JS/SWF files in your web page

You will need to include 5 JS files (provided in the package) in your web page: client.js, swfobject.js, fontdetect.js, ua-parser.js, miniorange-fp.js. Also you will need to copy other SWF files (provided in the package) to the js folder of your web application.

  • Create a directory named "js" inside the folder which contains your web page (the page where you will be including the JS files.
  • Copy all the JS and SWF files under this js directory.
  • Import all the JS file in your web page. For eg.
<html>
  <head>
    <title>ABC Inc.</title>
  </head>
  <body>
    <!--   Your content here  -->

    <script src="js/client.js"></script>
    <script src="js/swfobject.js"></script>
    <script src="js/fontdetect.js"></script>
    <script src="js/ua-parser.js"></script>
    <script src="js/murmurhash3.js"></script>
    <script src="js/miniorange-fp.js"></script>
  </body>
</html>

NOTE: Notice that all the JS file included at the end of the webpage and the order in which they are included.

Step 2: Calling miniOrange Register User API

Once you have includes JS files in your register-user web page and collected all the required information from user, you will need to make a Javascript call like this:

/*
 * isJSReady : This variable can be used to find out if the JS is ready to send request to the server.
 * fp.registerUser() : Javascript function you need to call for registering the user.
*/
if(isJSReady) {
  fp.registerUser(customerKey, userKey, phone, alternateEmail, kbaQA, mSuccess, mError);
}

Request Attributes

Attributes Data Type Description
CustomerKey String The customer ID that is provided to you. (Mandatory)
userKey String Email ID of the user you want to check. (Mandatory)
phone String Phone number of the User. (Optional)
alternateEmail String Alternate email of the User. (Optional)
kbaQA Array list Security Question/Answer list. Example provided below. (Mandatory)
mSuccess Javascript function Javascript function where you want to receive response if the request is successful. (Mandatory)
mError Javascript function Javascript function where you want to receive response if the request has failed. (Mandatory)

Response

Attributes Data Type Description
CustomerKey String The customerID you sent in the request
userKey String The username (email) you sent in the request
status String Overall status of the request (SUCCESS/ ERROR)
message String Additional message related to status.

Example and Code Snippet

Collect details like phone number, alternate email, security question/answer from your verified user and call miniOrange Register User API along with these details.

    function register() {
      /* Get your customerKey */
      var customerKey = '<YOUR_CUSTOMER_KEY>';

      /* Get the username (email) of the user */
      var username = 'demo@gmail.com';

      /* Get the User's Alternate Email of the user */
      var alternateEmail = 'alternate.email@gmail.com';

      /* Get the User's Phone number of the user */
      var phoneNumber = '+19xxxxxxxxx';

      /* Get the questions & answers selected by the user */
      var question1 = 'What is your favourite color?';
      var answer1 = 'red';

      var question2 = 'What is you frequent flyer number?';
      var answer2 = 'FL12548';

      /* Create the KBA Question/Answer array list */
      var kbaAnswers = [];

      /* Add Question 1 to the list */
      kbaAnswers.push({
        "question":question1,
        "answer":answer1
      });

      /* Add Question 2 to the list */
      kbaAnswers.push({
        "question":question2,
        "answer":answer2
      });

      /* Define the onSuccess function */
      var onRegisterSuccess = function(result) {
        /* Handle the Successful registration */
        console.log("Registration successful, Status: " + result.status);
      }

      /* Define the onError function */
      var onRegisterError = function(result) {
        /* Handle the registration error */
        console.log("Status: "+result.status + ", Reason: " + result.message);
      }

      /* Call Register User API */
      fp.registerUser(customerKey, username, phoneNumber, alternateEmail, kbaAnswers, onRegisterSuccess,
          onRegisterError);
    }

Evaluate Risk/Challenge API

evaluates risk based on the user and challenges the user if risk is high

You will need the following user's information to evaluate risk:

Attributes Description
customerKey Customer ID provided to you (Mandatory)
userKey Email ID of the user used while registration (Mandatory)

Step 1: Import miniOrange JS/SWF files in your web page

You will need to include 5 JS files (provided in the package) in your web page: client.js, swfobject.js, fontdetect.js, ua-parser.js, miniorange-fp.js. Also you will need to copy other SWF files (provided in the package) to the js folder of your web application.

-Create a directory named "js" inside the folder which contains your web page (the page where you will be including the JS files.
-Copy all the JS and SWF files under this js directory.
-Import all the JS file in your web page. For eg.

<html>
  <head>
    <title>ABC Inc.</title>
  </head>
  <body>
    <!--   Your content here  -->

    <script src="js/client.js"></script>
    <script src="js/swfobject.js"></script>
    <script src="js/fontdetect.js"></script>
    <script src="js/ua-parser.js"></script>
    <script src="js/murmurhash3.js"></script>
    <script src="js/miniorange-fp.js"></script>
  </body>
</html>

Note:Notice that all the JS file included at the end of the webpage and the order in which they are included.

Step 2: Calling miniOrange Register User API

Once you have includes JS files in your register-user web page and collected all the required information from user, you will need to make a Javascript call like this:

/*
 * isJSReady : This variable can be used to find out if the JS is ready to send request to the server.
 * fp.registerUser() : Javascript function you need to call for registering the user.
*/
if(isJSReady) {
  fp.registerUser(customerKey, userKey, phone, alternateEmail, kbaQA, mSuccess, mError);
}

Request Attributes

Attributes Data Type Description
customerKey String The customer ID that is provided to you. (Mandatory)
userKey String Email ID of the user you want to check. (Mandatory)
phone String Phone number of the User. (Optional)
alternateEmail String Alternate email of the User. (Optional)
kbaQA Array list Security Question/Answer list. Example provided below. (Mandatory)
mSuccess Javascript function Javascript function where you want to receive response if the request is successful. (Mandatory)
mError Javascript function Javascript function where you want to receive response if the request has failed. (Mandatory)

Response

Attributes Data Type Description
customerKey String The customerID you sent in the request
userKey String The username (email) you sent in the request
status String Overall status of the request (SUCCESS/ ERROR)
message String Additional message related to status.

You can call the evaluate risk API like this:

/*
 * isJSReady : This variable can be used to find out if the JS is ready to send request to the server.
 * fp.evaluateRisk() : Javascript function you need to call for evaluating the risk.
*/
if(isJSReady) {
  fp.evaluateRisk(customerKey, userKey, onEvaluateSuccess, onEvaluateError);
}

Example and Code Snippet

Collect details like phone number, alternate email, security question/answer from your verified user and call miniOrange Register User API along with these details.

    function register() {
      /* Get your customerKey */
      var customerKey = '<YOUR_CUSTOMER_KEY>';

      /* Get the username (email) of the user */
      var username = 'demo@gmail.com';

      /* Get the User's Alternate Email of the user */
      var alternateEmail = 'alternate.email@gmail.com';

      /* Get the User's Phone number of the user */
      var phoneNumber = '+19xxxxxxxxx';

      /* Get the questions & answers selected by the user */
      var question1 = 'What is your favourite color?';
      var answer1 = 'red';

      var question2 = 'What is you frequent flyer number?';
      var answer2 = 'FL12548';

      /* Create the KBA Question/Answer array list */
      var kbaAnswers = [];

      /* Add Question 1 to the list */
      kbaAnswers.push({
        "question":question1,
        "answer":answer1
      });

      /* Add Question 2 to the list */
      kbaAnswers.push({
        "question":question2,
        "answer":answer2
      });

      /* Define the onSuccess function */
      var onRegisterSuccess = function(result) {
        /* Handle the Successful registration */
        console.log("Registration successful, Status: " + result.status);
      }

      /* Define the onError function */
      var onRegisterError = function(result) {
        /* Handle the registration error */
        console.log("Status: "+result.status + ", Reason: " + result.message);
      }

      /* Call Register User API */
      fp.registerUser(customerKey, username, phoneNumber, alternateEmail, kbaAnswers, onRegisterSuccess,
          onRegisterError);
    }

Challenge User

When Evaluate Risk service sends WAIT_FOR_INPUT status, you should call this service to challenge the user with the obligation type returned by the Evaluate Risk service.

Request Attributes

Attributes Data Type Description
customerKey String The customer ID that is provided to you. (Mandatory)
userKey String Email ID of the user trying to continue the process. (Mandatory)
mSuccess Javascript function Javascript function where you want to receive response if the request is successful. (Mandatory)
mError Javascript function Javascript function where you want to receive response if the request has failed. (Mandatory)

Response

Attributes Data Type Description
customerKey String The customer ID you sent in the request.
userKey String The username (email) you sent in the request
kba Array list List of Questions user needs to answer. (Returned if obligation type was KBA.)
status String Overall status of the request (WAIT_FOR_INPUT/DENY/WAIT_TO_REGISTER_PROFILE/ERROR)
message String Additional message related to status.

You can call the challenge user API like this:

/*
 * isJSReady : This variable can be used to find out if the JS is ready to send request to the server.
 * fp.challenge() : Javascript function you need to call for challenging the user.
*/
if(isJSReady) {
  fp.challenge(customerKey, userKey, onChallengeSuccess, onChallengeError);
}

Example and Code Snippet


        var locInterval;
        function evaluateAndChallenge() {
        clearInterval(locInterval);
        if(isJSReady) {

        /* Get your customerKey */
        var customerKey = '<YOUR_CUSTOMER_KEY>';

        /* Get the username (email) of the user */)
        var userKey = 'demo@gmail.com';

        /* Define onEvaluateSuccess function */
        var onEvaluateSuccess = function(result) {
          console.log("Evaluate SUCCESS: " + result.status);

          if(result.status == 'SUCCESS') {

            /* Allow user to continue his process */
          } else if(result.status == 'WAIT_FOR_INPUT') {
            /*
            * - You should challenge the user.
            * - Handle UI based on the result.obligationType.
            * - You can inform user about the challenge type.
            */

            /* Define onChallengeSuccess function */
            var onChallengeSuccess = function(res) {
              if(res.status == 'SUCCESS') {

                /* Allow user to continue his process */
              } else {

                /* Look for res.message for what went wrong */
              }
            }

            /* Define the onChallengeError function */
            var onChallengeError = function(res) {

                /* Handle the error case */
            }

            /* Call the Challenge User API */
            fp.challenge(customerKey, userKey, onChallengeSuccess, onChallengeError);
          }
        }

        /* Define onEvaluateError function */
        var onEvaluateError = function(result) {
          console.log("ERROR: " + result.message);
          /* Handle error here */
        }

        /* Call the Evaluate Risk API */
        fp.evaluateRisk(customerKey, userKey, onEvaluateSuccess, onEvaluateError);

      } else {
        /* If the JS is not ready it waits and retry after 1 second. */
        locInterval = setInterval(function() { evaluateAndChallenge(); }, 1000);
      }
    }

Validate Challenge API

If the user is challenged, this API should be used to validate its challenge**

If the user was challenged, you may need to submit the response provided by the user to miniOrange for validation. For example, in case the obligationType returned by the Evaluate Risk API was KBA (Security Questions), you will need to submit the answers provided by the user to validate the user. Or if the obligationType was SMS, then you'll need to submit 6-digit OTP entered by the user to verify.

You will need the following user's information to validate challenge

Attributes Description
customerKey Customer ID provided to you (Mandatory)
userKey Email ID of the user used while registration (Mandatory)
otpToken OTP token entered by the user. (If obligationType was SMS or EMAIL)
kbaQA Questions/Answers list answered by the user. (If obligationType was KBA)
registerProfile Register this device's profile. (Mandatory)

NOTE:Either otpToken or kbaQA must be provided depending on the obligationType.

Step 1: Import miniOrange JS/SWF files in your web page

You will need to include 5 JS files (provided in the package) in your web page: client.js, swfobject.js, fontdetect.js, ua-parser.js, miniorange-fp.js. Also you will need to copy other SWF files (provided in the package) to the js folder of your web application.

  • Create a directory named "js" inside the folder which contains your web page (the page where you will be including the JS files.
  • Copy all the JS and SWF files under this js directory.
  • Import all the JS file in your web page. For eg.
    <html>
      <head>
        <title>ABC Inc.</title>
      </head>
      <body>
        ```<script src="js/swfobject.js"></script>
        <script src="js/fontdetect.js"></script>
        <script src="js/ua-parser.js"></script>
        <script src="js/murmurhash3.js"></script>
        <script src="js/miniorange-fp.js"></script>
      </body>
    </html>

NOTE: Notice that all the JS file included at the end of the webpage and the order in which they are included.

Step 2: Calling our Validate Challenge API

/*
 * isJSReady : This variable can be used to find out if the JS is ready to send request to the server.
 * fp.validate() : Javascript function you need to call for validating the challenge.
*/
if(isJSReady) {
  fp.validate(customerKey, userKey, otpToken, kbaQA, registerProfile, onValidateSuccess, onValidateError);
}

Request Attributes

Attributes Data Type Description
customerKey String The customer ID that is provided to you. (Mandatory)
userKey String Email ID of the user you want to check. (Mandatory)
otpToken String OTP token entered by user. (Pass blank string if obligationType KBA)
kbaQA Array list List of Questions/Answers provided by the user. (Pass empty array if obligationType was not KBA)
registerProfile Boolean Send TRUE if user selects (Checkbox checked by user) to register this device on challenge screen. Else send FALSE. (Mandatory)
mSuccess Javascript function Javascript function where you want to receive response if the request is successful. (Mandatory)
mError Javascript function Javascript function where you want to receive response if the request has failed. (Mandatory)

Response

Attributes Data Type Description
customerKey String The customerID you sent in the request
userKey String The username (email) you sent in the request
status String Overall status of the request (SUCCESS / KBA_ANSWERS_INVALID / INVALID_OTP / ERROR )
message String Additional message related to status.

Example and Code Snippet

  function validate() {
  /*  Get your customerKey */
  var customerKey = '<YOUR_CUSTOMER_KEY>';

  /* Get the username (email) of the user */
  var userKey = 'demo@gmail.com';

  /* Get the saveThisDevice checkbox value */
  var saveDevice = document.getElementById("saveDevice").checked;

  var kbaAnswers = [];
  var otpToken = '';

  /* If obligation type was KBA, then populate kba Question/Answer */
  if(type == 'KBA') {
    kbaAnswers.push({
      "question":'<QUESTION_1_ANSWERED_BY_USER>',
      "answer":'ANSWER_TO_QUESTION_1'
    });

    kbaAnswers.push({
      "question":'<QUESTION_2_ANSWERED_BY_USER>',
      "answer":'ANSWER_TO_QUESTION_2'
    });
  } else {

    /* Else get the OTP entered by the user */
    otpToken = document.getElementById("otpToken").value;
  }

  /* Define onValidationSuccess function */
  var onValidateSuccess = function(res) {
    if(res.status == 'SUCCESS') {

      /* Allow user to continue his process */
    } else if(res.status == 'KBA_ANSWERS_INVALID') {

      /* The answers are wrong. Please try again. */
    } else if(res.status == 'INVALID_OTP') {

      /* The OTP entered is invalid. Please try again. */
    }

  }

  /* Define OnValidationError function */
  var onValidateError = function(res) {
    console.log("Validate Error");
  }

  /* Call the validate API */
  fp.validate(customerKey, userKey, otpToken, kbaAnswers, saveDevice, onValidateSuccess, onValidateError);
}