Quickstart InWebo Virtual Authenticator

Updated on 01/15/2017

Introduction

Virtual Authenticator is the new 2FA browser token developed by inWebo Technologies.

It has the tremendous advantage of not requiring any installation for your users. It is downloaded along with the pages of your web site that need it – authentication page, new user subscription page – that’s it.

The purpose of this guide is to help you implement inWebo Virtual Authenticator successfully within your site. We also highly recommend that you read our guide dedicated to inWebo Helium/Virtual Authenticator Requirements and Persistence which also applies to Virtual Authenticator


General Principle

Virtual Authenticator consists in a javascript iframe that is call directly in your html logon page. It is hosted on the ult-inwebo.com domain.

Virtual Authenticator is only an OTP generator, nothing else. Once displayed in the logon page, it will prompt the user's pin code to generate an OTP. Finally, the login/OTP pair is inserted in the form fields and posted/submited (within the meaning of HTML) through the form.

Please note that once the OTP has been generated and posted, it has to be verified and validated by the inWebo servers using the AuthenticateExtended API.


Prerequisites

Note that Virtual Authenticator does not support Internet Explorer 8

For Virtual Authenticator to work, you need to have subscribed to one of inWebo offers.

When subscribing, you have access to inWebo Administration console, where you will add your Secure Sites.

Here is the list of parameters you need to configure:


Make sure inWebo Virtual Authenticator is activated for your service

In “Service Parameters” tab > “inWebo Authenticator & Virtual Authenticator”, make sure that “inWebo Virtual Authenticator (browser)” > “Activated” is set to “Yes”.


Create a Secure Site and activate Virtual Authenticator on it

In “Secure Sites” tab > “Secure Sites” section, you need to create a Secure Site (Web Services or Radius) that will load Virtual Authenticator. Use the dropdown list to add one.

The Secure Site window opens :

Called URL : This is the url that inWebo devices call whenever a user selects your service in his 'Secure Sites' list. It begins with http:// or https://

Authentication page : This is the page where authentication happens. It can be different from Called URL. Enter it beginning with //. It can be either a complete standard web url, or an IP address.

. Note1: if you are developing locally on you PC, 'localhost' is not permitted in the 'Authentication Page field'. Use 127.0.0.1 instead.

. Note2: Additionnal informations concerning all parameters can be found by clicking the online help : (i) pictogram.

When you are done, click “Add” button to validate your secure site configuration. Then before closing the window, click “Browser token activation” button. You should see a new non-editable field “Bookmark alias” to appear.

The Bookmark alias is a string like '1a2b2c4d4e6f7g8h9i0j1k2l3m4n5o6p' and is a unique identifier that will allow you to integrate Virtual Authenticator in your authentication and subscription pages.



Integration in your web pages

inWebo Virtual Authenticator integration is very simple. Simply add a few HTML tags in 2 places in your HTML source code. and you are set.

As a prerequisite, your logon page must include a html form with an explicite and unique 'name' tag, and also at least 2 input fields for the login and the otp, also with an explicit 'name' tag. The following example is corresponding to the secure site parameters entered above:

...
<form name="form" action=....>
  <input name="login" type="text"....>
  <input name="pwd" type="password"....>
</form>
...


Call Virtual Authenticator JavaScript in your HTML header

Add the following tag in your HTML header:

<script type="text/javascript" src="https://ult-inwebo.com/va/client.js"></script>

Insert configuration parameters in your HTML body

These parameters are located in a div tag in the body of your page.

<div id="myContainer" style="display:none;"></div>
 
<div id="iwVaDetect" data-action="authentication" data-container="myContainer"
      data-lang="en" data-alias="1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p" data-width="auto"></div>

Available start tag attributes:

  • id ⇒ id of the Virtual Authenticator starting div. Leave “iwVaDetect” for basic implementation – mandatory
  • data-container=“myContainer” ⇒ id of the div element that will host the display of Virtual Authenticator – mandatory
  • data-alias=“1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p” ⇒ Bookmark ID alias – mandatory
  • data-action = one of the following value: – mandatory
    • authentication: for users authentication.
    • activation: for users to activate their browser. They are asked to enter a secure site ID.
    • pushactivation: for users to activate their browser, with a push notification received on their inWebo registered mobile.
    • unlock: for users to unlock their browser token. An unlocking code is asked to the user in order to be able to redefine their pin code.
    • changepin: to force users changing their pin code.
  • data-nopin: boolean (0 or 1). Default value=“0” ⇒ if set to 1, authentication without pin forced
  • data-silent-run: boolean. Default value=“0”. If set to 1 no splash screen is displayed when Virtual Authenticator loads and if no pin is required for authentication then the action is performed silently
  • data-quiet-start: boolean (0 or 1). Default value=“0”⇒ if set to 1 no splash screen is displayed when Virtual Authenticator loads
  • data-lang: Default value='auto'. Sets the language of Virtual Authenticator interface. Can be set to 'fr' or 'en'. 'Default' means that the user's prefered langage is used.
  • data-width: Default value=“M” ⇒ sets the size of the Virtual Authenticator interface - see below

Available interface widths:

  • auto: iframe size is set depending on the viewport width (responsive mode)
  • fixed size:
    • “S” or “small” ⇒ good for screen having a width from 320 to 349px
    • “M” or “medium” ⇒ good for screen having a width from 350 to 449px
    • “L” or “Large” ⇒ good for screen having a width from 450 to 599px
    • “XL” or “xlarge” ⇒ good for screen having a width - equal to or over 600px
  • custom numeric size : set a size in pixel, e.g. 400


Table summarizing all tag attributes and values:

Start Tags Default Value Other possible values Explanation
id iwVaDetect any other (advanced) id of the Virtual Authenticator starting div. Leave “iwVaDetect” for basic implementation – mandatory
data-container none any other id of the div element that will host the display of Virtual Authenticator – mandatory
data-alias none - Bookmark ID alias – mandatory
data-action none authentication for users authentication
activation for users to activate their browser token. They are prompted to enter a secure site ID
pushactivation for users to activate their browser, with a push notification received on their inWebo registered mobile
unlock for users to unlock their browser token. Users a prompted to enter an inWebo unlock code to reset their pin code
changepin to allow users to change their pin code
data-nopin 0 1 Boolean. If set to 1, authentication without pin is forced
data-silent-run 0 1 Boolean. If set to 1 no splash screen is displayed when Virtual Authenticator loads and if no pin is required for authentication then the action is performed silently
data-quiet-start 0 1 Boolean. If set to 1 no splash screen is displayed when Virtual Authenticator loads
data-lang auto“fr” or “en” Sets the language of Virtual Authenticator interface. Default value “auto” means that the user's preferred langage is used.
data-width auto String. Sets the size of the Virtual Authenticator interface:
“S” or “small” good for screen having a width from 320 to 349px
“M” or “medium” good for screen having a width from 350 to 449px
“L” or “Large” good for screen having a width from 450 to 599px
“XL” or “xlarge” good for screen having a width - equal to or over 600px


Optional tags:

  • Action authentication: you can insert the login that will be authenticated in your page and Virtual Authenticator will use it (usefull in two-steps auth scenarios)
<div id="inwebologin" style="display:none;">mylogin</div>


  • Action activation: you can insert an inWebo activation code in your page. (Usefull in custom provisionning workflows to pre-fill the secure site id field during activation)
<div id="inweboactivationcode" style="display:none;">842693752</div>



Basic implementation

Just add the tags described above in the header and the body of your HTML page and you are set.

inWebo Virtual Authenticator will be displayed in the container you have set in the “data-container” attribute of the “inWeboVaDetect” parameter div element.

Available actions assignable to “data-action=” are:

  • authentication: for user authentication.
  • activation: for users to activate their browser token. They are prompted to enter a secure site ID.
  • pushactivation: for users to activate their browser token with a push notification received on their inWebo registered mobile.
  • unlock: for users to unlock their browser token. Users a prompted to enter an inWebo unlock code to reset their pin code.
  • changepin: to allow users to change their pin code.



Advanced implementation

Start Virtual Authenticator with a javascript function

You can start inWebo Virtual Authenticator with a custom javascript function. In this case, the id of the parameter div element must be set to something other than “iwVaDetect”.

  iwstart("myStart", function(iw, data) {
     //handle action result here
  });


Start Virtual Authenticator in a popup

Assuming “myContainer” is the id of the div element that will host the display of Virtual Authenticator, you can start the token in popup mode this way:

  iwpopup("myContainer", "myStart", function() {
     iwstart("myStart", function(iw, data) {
          //handle action result here
     });
  });


Start Virtual Authenticator when the document is ready

It is always recommended to start Virtual Authenticator when the page hosting the javascript token is fully loaded (i.e. when the DOM is fully loaded). You can use your own instance of jQuery, use the jQuery instance that is loaded with Virtual Authenticator or any other javascript instruction of your liking to start the token when the page (or document) is ready.

    VA_jQuery(document).ready(function(){
        iwpopup("myContainer", "myStart", function() {
            iwstart("myStart", function(iw, data) {
                //handle action result here
            });
        });
    });


You can also start Virtual Authenticator on any other DOM event, typically on a “click” event:

    VA_jQuery("#myButton").on("click", function(){
        iwpopup("myContainer", "myStart", function() {
            iwstart("myStart", function(iw, data) {
                //handle action result here
            });
        });
    });


Handle Virtual Authenticator action result

When you start Virtual Authenticator with a custom javascript function, you can handle the result of the action in the iwstart function callback:

    function(iw, data) {
        //handle action result here
    }

The iwstart function callback receives a data object which contains the following properties:

  data.
    |_ action: the action for which VA was started
    |_ type: type of message: error / warning / success
    |_ code: error code
    |_ result: an object

The “result” property is an object

  • in case of an error, warning or info message it contains a property name “reason” which is a short string giving more information on the context
  • in case of a success message:
    • if action is authentication: data.result contains the authentication data (form & fields definition, values)
    • other actions: data.result.reason contains a short string giving more information on the context or might be empty


Error result

  • data.action = <action>
  • data.type = “error”
  • data.code = “nok”
  • data.result.reason:
    • “unsupported_browser” ⇒ browser is not supported, typically IE8
    • “va_unreachable” ⇒ VA servers could not be reached
    • “force_close” ⇒ an error has forced Virtual Authenticator app to stop
    • “no_container” ⇒ the container declared could not be found
    • “no_action” ⇒ the action is undefined or there is a mispelling in the action name
    • “no_start” ⇒ Virtual Authenticator failed to start
    • “no_network” ⇒ a network error occured
    • “bad_url” ⇒ the URL of the page loading Virtual Authenticator does not mach a secure site URL (authentication only)
    • “no_profile” ⇒ no profile found for the current action and the current Secure Site
    • “no_push” ⇒ no device found for push actions for the current profile


Warning result

  • data.action = <action>
  • data.type= “warning”
  • data.code = “nok”
  • data.result.reason:
    • “no_push” ⇒ no device found for push actions for the current profile but another action is possible


Success result

  • data.action = <action>
  • data.type= “success”
  • data.code = “ok”
  • data.result = <authentication values>

<authentication values> is an object with the following properties:

  • “form” : name of the form in authentication page,
  • “fields” : array of fields to fill,
  • “values”: array of values to pass into fields


Info result

  • data.action = <action>
  • data.type = “info”
  • data.code = “info”
  • data.result.reason:
    • “ui_shown” ⇒ Virtual Authenticator UI is fully loaded
    • “user_close” ⇒ Virtual Authenticator popup has been closed by the user (only applies to popup mode)


Examples

Typical handling of a successful authentication:

   if (data.type == "success" && data.code == "ok" && data.action == "authentication") {
        iw.insertFields(data.result);
   }

Typical trapping of nok:no profile cases (i.e a non trusted/enrolled browser):

    if (data.type == "error" && data.code == "nok" && data.result.reason == "no_profile") {
        //your logic here
    }

Typical handling of a successful activation:

    if (data.type == "success" && data.code == "ok" && data.action == "activation") {
        //your logic here
        //you can restart in 'authenticate' mode
    }

Typical way of detecting that Virtual Authenticator UI display is ready

    if (data.type == "info" && data.action == "ui_shown") {
        //your logic here
    }


Full sample with action chaining

  • Javascript code (in HTML header, i.e between <head> </head>)
<script type="text/javascript">
VA_jQuery(document).ready(function(){
   iwpopup("myContainer", "myStart", function() {
      iwstart("myStart", function(iw, data) {
 
        //Successful authentication
	if (data.action == "authentication" && data.code == "ok") {
	   iw.insertFields(data.result);
	}
 
        //Virtual Authenticator is not activated
	if (data.type == "error" && data.code == "nok" && data.result.reason == "no_profile") {
 
           //We terminate the previous instance of Virtual Authenticator
	   iwterminate();
 
           //We encapsulate the restart of Virtual Authenticator on action "activation" in a setTimeout
	   setTimeout(function() {
	      iwstart("myStartActivate", function(iw, data) {
		//handle successful activation here
	      });
           }, 0);			
	}
      });
   });
});
</script>


  • HTML Tags in the body (between <body> </body>):
<div id="myStart" data-action="authentication" data-container="myContainer" data-quiet-start="1"
	  data-lang="auto" data-width="M" data-alias="1a2b2c4d4e6f7g8h9i0j1k2l3m4n5o6p"></div>
<div id="myStartActivate" data-action="activation" data-container="myContainer" data-quiet-start="1"
	  data-lang="auto" data-width="M" data-alias="1a2b2c4d4e6f7g8h9i0j1k2l3m4n5o6p"></div>
<div id="myContainer"></div>

Note: The data.alias '1a2b2c4d4e6f7g8h9i0j1k2l3m4n5o6p' is to be replaced by your own “bookmark alias” as shown in your secure site.


Function iwterminate()

This function can be used to properly terminate an instance of Virtual Authenticator If you plan to immediately restart another instance of the token, it is highly recommended to encapsulate the new call to iwstart() in a setTimeout function. This will ensure that the previous instance has been completely removed from the browser context.