Quickstart inWebo Virtual Authenticator

Note

the Activation Code was formerly called "Secure Site ID" in some authentication tools or in the documentation.
Please note that a "Secure Site ID" refers to an activation code.

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 Best practices for securing browser enrollments which also applies to Virtual Authenticator

General Principle

Virtual Authenticator consists of a javascript iframe that is called directly from within 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 the 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 information concerning all parameters can be found by clicking the online help : (i) pictogram.

Important: "Authentication Page" field

This field has a security target as this value will be compared to the user's browser URL to prevent phishing attacks. Thus, it is crucial the URL entered in "Authentication field" matchs exactly what users will enter in their web browser.

When developing/testing, it's a common mistake that prevent Virtual Authenticator to be displayed. If you've entered an IP address in this field, you must also access with this same IP address on your web browser for Virtual Authenticator to work and be displayed.

When you are done, click the “Add” button to validate your secure site configuration. Then before closing the window, click the “Browser token activation” button. You should see a new non-editable field “Bookmark alias” 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 explicit 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 an Activation code.

  • 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 'en', 'fr', 'de', 'es', 'nl'. 'auto' means that the user's prefered langage is used.

• data-width: Default value=“M” ⇒ sets the size of the Virtual Authenticator interface - see below

• data-randompad: boolean (0 or 1). Default value=“0”⇒ if set to 1 numeric keys on keypad are displayed in a random order

• data-usekeypad: boolean (0 or 1). Default value=“1”⇒ if set to 0 Virtual Authenticator is displayed without the virtual keypad

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:

Optional tags:

• Action authentication: you can insert the login that will be authenticated in your page and Virtual Authenticator will use it (useful in two-step auth scenarios)

<div id="inwebologin" style="display:none;">mylogin</div>

• Action activation: you can insert an inWebo activation code in your page. (Useful in custom provisioning workflows to pre-fill the "Activation code" field during activation)

<div id="inweboactivationcode" style="display:none">123456789</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 “iwVaDetect” 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 an Activation code.

• 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 == "error" && data.code == "nok" && data.result.reason == "no_profile") {
        //your logic here
    }

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
						if (data.type == "success" && data.code == "ok" && data.action == "activation") {
							window.location.href = window.location.href;
						}
					});
				}, 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.