FAQ

Step by Step guide to use miniOrange Strong Authentication Product

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.
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 i’m me 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.
* These authentication methods require miniOrange i’m me mobile app available for Android and Apple smartphones.
** This method require hardware token provided by miniOrange.

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.


Integrating with miniOrange Strong Authentication Service

There are 2 scenarios for calling Rest APIs:

  1. Your end users are enrolled with us: We have the information about your users and their configurations.
  2. Your end users are NOT enrolled with us: We don’t have any information about your users, but you will provide the information while calling our 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
KBA (Security Questions) *
Soft Token *
Hardware Token *
Push Notifications *
Mobile Authentication *
Voice Authentication *

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

  1. Your end users are enrolled with us

    If your End Users are enrolled with us along with OTP over SMS, OTP over EMAIL, Out-of-Band SMS & Out-of-Band EMAIL, you can also use Soft Token, Hardware Token, Push Notifications, Mobile Authentication and Voice Authentication as the authentication methods. These additional methods of authentication require prior configurations before they can be used. You need to send 2 separate requests, one for generating the OTP and second for validating the OTP.

    NOTE:

    • In case of Soft Token or Hardware Token, only validation request needs to be sent.
    • In case of Out-of-Band SMS, Out-of-Band EMAIL, Push Notifications or Voice Authentication, only generation request needs to be sent.

    1. Calling our Generate OTP rest API (except for KBA)

      To generate an OTP, you need to make a HTTP POST request to our Generate Rest API. Our Generate Rest API accepts the JSON input in the following format:

      Rest Service URL: (Contact Us)

      /* JSON Object format for generation request with only userKey */ { "customerKey":"abc", /* Your customer key */ "user": { "userKey":"xyz@example.com" /* The User key that you provided to us during enrolment */ } "secondFactorAuthType":"SMS", "transactionName":"transaction-details", }

      AttributeDescription
      customerKey *Your customer key.
      userKey *This is the key that you provided while enrolling the user with us.
      secondFactorAuthTypeThe type of method you want this user to authenticate with. If this field is not provided, the authentication method set by the user will be used for authentication. Valid values: SMS, EMAIL, OUT OF BAND SMS, OUT OF BAND EMAIL, PUSH NOTIFICATIONS, SOFT TOKEN, MOBILE AUTHENTICATION, VOICE AUTHENTICATION
      transactionNameAny transaction details that you would like to send to user to give information about the transaction. (Max limit 30 characters)

      * These fields are mandatory.


      The following is the JSON Response generated by the Generate Rest API.

      /* JSON Response Object for Generation Request */ { "requestId":"req-123", "responseType":"GENERATE", "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "emailDelivery": { /* in case email is sent to user */ "contact":"xyz@example.com", "sendStatus":"SUCCESS", "sendTime":"Aug 5, 2013 5:17:17 PM" } "phoneDelivery": { "contact":"1234567890", "sendStatus":"SUCCESS", "sendTime":"Aug 5, 2013 5:14:07 PM" } "message":"Successfully Generated", "statusCode":"SUCCESS" "qrCode":"qr-code-value" /* Can be used to display QR code in case user has opted for mobile authentication*/ }

      AttributeDescription
      requestIdThis is the request ID for your generation request.
      responseTypeThis shows the type of response i.e. Response for Generate request or Validate request. Valid values: GENERATE, VALIDATE
      customerKeyYour customer key.
      userKeyThe user key provided in the generation/validation request.
      emailDeliveryThe email delivery status. It is provided in case authentication is done through email.
      phoneDeliveryThe phone delivery status. It is provided in case authentication is done through to mobile. contact The contact OTP sent on.
      sendStatusThe status of sending the above contact.
      Valid values: SUCCESS, FAILED
      sendTimeTimestamp showing time of sending.
      messageAn additional message showing overall status of the request.
      statusCodeOverall status of the generation/validation request.
      Valid values: SUCCESS, FAILED, ERROR
      qrCodeIn case user has opted for mobile authentication, this value contains base64 encoded string that can be used to show QR Code image (JPG format) for scanning.


    2. Calling our Validate OTP rest API (except for KBA)

      To validate an OTP, you need to make an HTTP POST request to our Validate Rest API. Our Validate Rest API accepts the JSON input in the following format:

      Rest Service URL: (Contact Us)

      /* JSON Object for Validation Request with only userKey */ { "customerKey":"abc", /* Your customer key */ "user": { "userKey":"xyz@domain.com" /* The User key that you provided to us during enrolment */ } "otpToken":"000000" }

      AttributeDescription
      customerKey *Your customer key.
      userKey *This is the key that you provided while enrolling the user with us.
      otpToken *The OTP token user entered for validation.

      * These fields are mandatory.


      The following is the JSON Response generated by the Validate Rest API.

      /* JSON Response Object for Generation Request */ { "requestId":"req-123", "responseType":"VALIDATE", "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "otpToken":"000000", "message":"Successfully Validated", "statusCode":"SUCCESS" }

      AttributeDescription
      requestIdThis is the request ID for your generation request.
      responseTypeThis shows the type of response i.e. Response for Generate request or Validate request.
      Valid values: GENERATE, VALIDATE
      customerKeyYour customer key.
      userKeyThe user key provided in the validation request.
      otpTokenThe OTP token user entered for validation.
      messageAn additional message showing overall status of the request.
      statusCodeOverall status of the generation/validation request.
      Valid values: SUCCESS, FAILED, ERROR


    3. Calling our Get KBA Questions Rest API

      You need to call a different rest API to get the KBA questions for validating the user.

      Rest Service URL: (Contact Us)

      /* JSON Object for Validation Request with only userKey */ { "customerKey":"abc", /* Your customer key */ "userKey":"xyz@domain.com" /* The User key that you provided to us during enrolment */ }

      AttributeDescription
      customerKey *Your customer key.
      userKey *This is the key that you provided while enrolling the user with us.

      The following is the JSON Response generated by the Get KBA Questions Rest API.

      /* JSON Response Object for Get KBA questions Request */ { "responseType":"INFO", "customerKey":"abc", "userKey":"xyz@example.com" "kba": [ { "question":"your configured question" }, { "question":"your configured question" }, ] "message":"The question registered for this user are provided in this response.", "statusCode":"SUCCESS" }

      AttributeDescription
      responseTypeThis shows the type of response i.e. Response for Get request or Validate request. Valid values: INFO
      customerKeyYour customer key.
      userKeyThe user key provided in the get request.
      kbaThe list of questions configured by the user.
      messageAn additional message showing overall status of the request.
      statusCodeOverall status of the request. Valid values: SUCCESS, FAILED, ERROR


    4. Calling our Validate KBA Questions Rest API

      Rest Service URL: (Contact Us)

      /* JSON Request Object for Validate KBA questions */ { "customerKey":"abc", "userKey":"xyz@example.com" "kba": [ { "question":"your configured question", "answer":"user’s answer" }, { "question":"your configured question", "answer":"user’s answer" } ] }

      AttributeDescription
      customerKeyYour customer key.
      userKeyThe user key provided in the get request.
      kbaThe list of questions and answers to verify.

      The following is the JSON Response generated by the Validate KBA Questions Rest API.

      /* JSON Response Object for Validate KBA questions Request */ { "responseType":"VALIDATE", "customerKey":"abc", "userKey":"xyz@example.com" "kba": [ { "question":"your configured question", "answer":"user’s answer" }, { "question":"your configured question", "answer":"user’s answer" } ] "message":"The answers you have provided are correct.", "statusCode":"SUCCESS" }

      AttributeDescription
      responseTypeThis shows the type of response i.e. Response for Get request or Validate request. Valid values: VALIDATE
      customerKeyYour customer key.
      userKeyThe user key provided in the get request.
      kbaThe list of questions and answers you provided for validation.
      messageAn additional message showing overall status of the request.
      statusCodeOverall status of the request. Valid values: SUCCESS, FAILED, ERROR


    5. Some more Examples

      Generation RequestGeneration Response
      { "customerKey":"abc", "user": { "userKey":"xyz@example.com" } }
      In this case the authentication type set by user will used for authentication. Let say user has set OTP over SMS as his authentication method.
      The response for this would be:
      { "requestId":"req-123", "responseType":"GENERATE", "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "phoneDelivery": { "contact":"1234567890", "sendStatus":"SUCCESS", "sendTime":"Aug 5, 2013 5:14:07 PM" } "message":"Successfully Generated", "statusCode":"SUCCESS" }
      Let say you want to override the method saved by the user and use PUSH NOTIFICATION instead:
      { "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "secondFactorAuthType":"PUSH NOTIFICATIONS" "transactionName":"Buy Casio Watch $200" }
      This will work only if user has configured push notification on this mobile.
      User will receive push notification on his mobile with transaction details that you provided and user Accepts the notification:
      { "requestId":"req-123", "responseType":"VALIDATE", "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "message":"Successfully Validated", "statusCode":"SUCCESS" }
      You can notice that the responseType in this case is VALIDATE. For Out-of-Band SMS/EMAIL or PUSH NOTIFICATION you directly get the validate response.

      Validation RequestValidation Response
      { "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "otpToken":"123456" }
      In this case the authentication type set by user will used for authentication. Let say user has set OTP over SMS as his authentication method.
      The response for this would be:
      { "requestId":"req-123", "responseType":"VALIDATE", "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "otpToken":"123456" "message":"Successfully Validated", "statusCode":"SUCCESS" }
      Let say you want to override the method saved by the user and use SOFT TOKEN instead:
      { "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "secondFactorAuthType":"SOFT TOKEN" "otpToken":"123456" }
      This will work only if user has configured Soft Token on this mobile.
      The response for this would be:
      { "requestId":"req-123", "responseType":"VALIDATE", "customerKey":"abc", "user": { "userKey":"xyz@example.com" } "otpToken":"123456" "message":"Successfully Validated", "statusCode":"SUCCESS" }



  2. Your end users are NOT enrolled with us

    If your End Users are not enrolled with us, you can still use our authentication service. In this case, you will need to provide us the phone number or email where you want us to send the OTP.

    1. Calling our Generate OTP Rest API

      To generate an OTP, you need to make a HTTP POST request to our Generate Rest API. Our Generate Rest API accepts the JSON input in the following format:

      Rest Service URL: (Contact Us)

      /* JSON Object format for generation request */ { "customerKey":"abc", /* Your customer key */ "user": { "phone":"1234567890" /* phone number to send OTP to */ "email":"xyz@example.com" /* The email to send OTP to */ } "secondFactorAuthType":"SMS AND EMAIL" "transactionName":"transaction-details", }

      AttributeDescription
      customerKey *Your customer key.
      phoneThe phone number where you would like us to send OTP to.
      emailThe email ID where you would like us to send OTP to.
      secondFactorAuthType *The authentication method you would like to use. Valid values: SMS, EMAIL, SMS AND EMAIL, OUT OF BAND SMS, OUT OF BAND EMAIL
      transactionNameAny transaction details that you would like to send to user to give information about the transaction. (Max limit 30 characters)

      * These fields are mandatory.


      NOTE: Either phone or email is required for us to send OTP. If both are provided then OTP will be sent on both the contacts.


      The following is the JSON Response generated by the Generate Rest API.

      /* JSON Response Object for Generation Request */ { "requestId":"req-123", "responseType":"GENERATE", "customerKey":"abc", "user": { "phone":"1234567890" "email":"xyz@example.com" } "emailDelivery": { /* in case email is sent to user */ "contact":"xyz@example.com", "sendStatus":"SUCCESS", "sendTime":"Aug 5, 2013 5:17:17 PM" } "phoneDelivery": { /* in case OTP is sent over phone */ "contact":"1234567890", "sendStatus":"SUCCESS", "sendTime":"Aug 5, 2013 5:14:07 PM" } "message":"Successfully Generated", "statusCode":"SUCCESS" }

      AttributeDescription
      requestIdThis is the request ID for your generation request.
      responseTypeThis shows the type of response i.e. Response for Generate request or Validate request.
      Valid values: GENERATE, VALIDATE
      customerKeyYour customer key.
      userKeyThe user key provided in the generation/validation request.
      emailDeliveryThe email delivery status. It is provided in case authentication is done through email.
      phoneDeliveryThe phone delivery status. It is provided in case authentication is done through to mobile.
      contactThe contact OTP sent on.
      sendStatusThe status of sending the above contact.
      Valid values: SUCCESS, FAILED
      sendTimeTimestamp showing time of sending.
      messageAn additional message showing overall status of the request.
      statusCodeOverall status of the generation/validation request. Valid values: SUCCESS, FAILED, ERROR


    2. Calling our Validate OTP Rest API

      To validate an OTP, you need to make an HTTP POST request to our Validate Rest API. Our Validate Rest API accepts the JSON input in the following format:

      Rest Service URL: (Contact Us)

      /* JSON Object for Validation Request */ { "customerKey":"abc", /* Your customer key */ "user": { "phone":"1234567890" /* phone number provided during generation request */ "email":"xyz@example.com" /* email ID provided during generation request */ } "otpToken":"000000" }

      AttributeDescription
      customerKey *Your customer key.
      phoneThe phone number where you would like us to send OTP to.
      emailThe email ID where you would like us to send OTP to.
      otpTokenThe OTP token entered by the user to validate.

      * These fields are mandatory.


      The following is the JSON Response generated by the Validate Rest API.

      /* JSON Response Object for Generation Request */ { "requestId":"req-123", "responseType":"VALIDATE", "customerKey":"abc", "user": { "phone":"1234567890" "email":"xyz@example.com" } "otpToken":"000000", "message":"Successfully Validated", "statusCode":"SUCCESS" }

      AttributeDescription
      requestIdThis is the request ID for your generation request.
      responseTypeThis shows the type of response i.e. Response for Generate request or Validate request. Valid values: VALIDATE
      customerKeyYour customer key.
      phoneThe phone number provided during the validation request.
      emailThe email ID provided during the validation request.
      otpTokenThe OTP token user entered for validation.
      messageAn additional message showing overall status of the request.
      statusCodeOverall status of the generation/validation request. Valid values: SUCCESS, FAILED, ERROR


    3. Some more Examples

      Generation RequestGeneration Response
      { "customerKey":"abc", "user": { "phone":"1234567890" } "secondFactorAuthType":"SMS" }
      The response for this would be:
      { "requestId":"req-123", "responseType":"GENERATE", "customerKey":"abc", "user": { "phone":"1234567890" } "phoneDelivery": { "contact":"1234567890", "sendStatus":"SUCCESS", "sendTime":"Aug 5, 2013 5:14:07 PM" } "message":"Successfully Generated", "statusCode":"SUCCESS" }
      { "customerKey":"abc", "user": { "phone":"1234567890" } "secondFactorAuthType":"OUT OF BAND SMS" } User will receive an SMS with Accept and Deny link on this phone number. If user clicks accept link, the response will be:
      { "requestId":"req-123", "responseType":"VALIDATE", "customerKey":"abc", "user": { "phone":"1234567890" } "message":"Successfully Validated", "statusCode":"SUCCESS" }
      You can notice that the responseType in this case is VALIDATE. For Out-of-Band SMS/EMAIL, you directly get the validate response.

      Validation RequestValidation Response
      { "customerKey":"abc", "user": { "phone":"1234567890" } "otpToken":"123456" }
      Suppose only phone was provided during the generation request.
      The response for this would be:
      { "requestId":"req-123", "responseType":"VALIDATE", "customerKey":"abc", "user": { "phone":"1234567890" } "otpToken":"123456" "message":"Successfully Validated", "statusCode":"SUCCESS" }



  3. Sample Java Code for calling our rest API

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

    public String callGenerateRestApi() { /* The generation rest api url which needs to be called to generate the OTP */ String generateUrl = "URL-provided-by-us"; /* The JSON string containing the request information */ String jsonRequestString = "{"customerKey":"abc","user":{"userKey":"456"}}"; /* Generating Authorization Code for miniOrange */ /* (Here we are using Apache.Shiro library to generate SHA-512 Hash) */ String stringToHash = <YOUR_CUSTOMER_KEY> + <YOUR_API_KEY>; String hashValue = new Sha512Hash(stringToHash).toHex(); /* 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 Hash value as Authorization Code HTTP Header */ postRequest.setHeader("Authorization-Code",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; }


More Faq's