Strong Authentication API Guide
A guide on how to use miniOrange Strong Authentication APIs.

Overview

miniOrange Strong Authentication Service provides various types of authentication methods which can be easily configured and used for authentications.

Types of authentication methods provided are:

MethodsDescription
OTP over SMSA 6-8 digit OTP is sent on user’s mobile which he then enters to validate himself.
OTP over EMAILA 6-8 digit OTP is sent on user’s email which he then enters to validate himself.
Out-of-Band SMSAn SMS is sent on user’s mobile containing links to Accept or Deny the transaction.
Out-of-Band EMAILAn email is sent on user containing links to Accept or Deny the transaction.
Phone VerificationUser receive a voice call telling a 4-8 digit numeric key which he needs to enter to authenticate himself.
KBA (Security Questions)User is asked to answer some questions which he had configured.
Soft Token *User is asked to enter the 6 digit code generated on his mobile by our miniOrange Authenticator mobile app.
Hardware Token **User needs to plug in his hardware token to validate himself.
Push Notification *User receives a push notification on his mobile to Accept or Deny the transaction.
Mobile Authentication *User needs to scan a QR code from our i’m me mobile app to validate himself.
Voice Authentication *User needs to validate himself through his voice.
Google Authenticator ***User is asked to enter the 6 digit code generated on his mobile by Google Authenticator app.
* These authentication methods require miniOrange i’m me mobile app available for Android and Apple smartphones.
** This method require hardware token provided by miniOrange.
*** This method require Google Authenticator app.

NOTE: Some methods need some prior configuration by the end users before they can be used for authentication.

This guide will help you integrate your application with miniOrange Strong Authentication Service using our Rest APIs.


Pre-requisites

Integrating with miniOrange Strong Authentication Service

There are 2 scenarios for calling Rest APIs:


We will cover these 2 scenarios one by one in detail.

The authentication methods supported by these 2 scenarios are:

End users Enrolled with usEnd users NOT Enrolled with us
OTP over SMSOTP over SMS
OTP over EMAILOTP over EMAIL
Out-of-Band SMSOut-of-Band SMS
Out-of-Band EMAILOut-of-Band EMAIL
Phone VerificationPhone Verification
KBA (Security Questions) *
Soft Token *
Hardware Token *
Push Notifications *
Mobile Authentication *
Voice Authentication *
Google Authenticator *

* Prior configuration by end user is necessary for these types of authentications.

Sample JAVA code to call our rest API: (Here we are using Apache HttpClient to call our rest API)

public String callChallengeRestApi() { /* The challenge rest api url which needs to be called to challenge the user. */ String generateUrl = "URL-provided-by-us"; /* The customer Key provided to you */ String customerKey = "<YOUR_CUSTOMER_KEY>"; /* The customer API Key provided to you */ String apiKey = "<YOUR_API_KEY>"; /* Current time in milliseconds since midnight, January 1, 1970 UTC. */ String currentTimeInMillis = String.valueOf(System.currentTimeMillis()); /* Creating the Hash using SHA-512 algorithm (Apache Shiro library) */ String stringToHash = customerKey + currentTimeInMillis + apiKey; String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase(); /* The JSON string containing the request information */ String jsonRequestString = "{\"customerKey\":\"" + customerKey + "\",\"username\":\"xyz@example.com\"}"; /* Initializing default Http Client */ HttpClient httpClient = new DefaultHttpClient(); HttpPost postRequest = new HttpPost(generateUrl); /* Setting jsonRequestString as StringEntity */ StringEntity input = new StringEntity(jsonRequestString); input.setContentType("application/json"); postRequest.setEntity(input); /* Setting the Authorization Header values */ postRequest.setHeader("Customer-Key", customerKey); postRequest.setHeader("Timestamp", currentTimeInMillis); postRequest.setHeader("Authorization", hashValue); /* Calling the rest API */ HttpResponse httpResponse = httpClient.execute(postRequest); /* If invalid response is received, throwing a Runtime Exception */ if (httpResponse.getStatusLine().getStatusCode() != 200) { throw new RuntimeException("Invalid response received from authentication server. HTTP error code: " + response.getStatusLine().getStatusCode()); } /* If a valid response is received, get the JSON response string */ BufferedReader br = new BufferedReader(new InputStreamReader((httpResponse.getEntity().getContent()))); String output, jsonResponseString = ""; while ((output = br.readLine()) != null) { jsonResponseString += output; } httpClient.getConnectionManager().shutdown(); return jsonResponseString; }


Sample PHP code to call our rest API

<?php function callGenerateRestApi() { /* The challenge rest api url which needs to be called to challenge the user. */ $generateUrl = "URL-provided-by-us"; /* The customer Key provided to you */ $customerKey = "<YOUR_CUSTOMER_KEY>"; /* The customer API Key provided to you */ $apiKey = "<YOUR_API_KEY>"; /* Current time in milliseconds since midnight, January 1, 1970 UTC. */ $currentTimeInMillis = round(microtime(true) * 1000); /* Creating the Hash using SHA-512 algorithm */ $stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) . $apiKey; $hashValue = hash("sha512", $stringToHash); /* The Array containing the request information */ $jsonRequest = array("customerKey" => $customerKey, "username" => "xyz@example.com"); /* JSON encode the request array to get JSON String */ $jsonRequestString = json_encode($jsonRequest); $customerKeyHeader = "Customer-Key: " . $customerKey; $timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', '' ); $authorizationHeader = "Authorization: " . $hashValue; /* Initialize curl */ $ch = curl_init(); curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json", $customerKeyHeader, $timestampHeader, $authorizationHeader)); curl_setopt($ch, CURLOPT_URL, $generateUrl); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE); curl_setopt($ch, CURLOPT_VERBOSE, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequestString); curl_setopt($ch, CURLOPT_POST, 1); /* Calling the rest API */ $result = curl_exec($ch); if (curl_errno($ch)) { print curl_error($ch); } else { curl_close($ch); } /* If a valid response is received, get the JSON response */ $response = (array)json_decode($result); $status = $response['statusCode']; if($status == 'SUCCESS') { return "SUCCESS"; } else { return "FAILED: " . $response['message']; } } ?>