Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 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.

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:

Code Block
languagexml
...
<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:

Code Block
languagexml
<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.

Code Block
languagexml
<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

  • 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:

Start TagsDefault ValueOther possible valuesExplanation
idiwVaDetectany other (advanced)id of the Virtual Authenticator starting div. Leave “iwVaDetect” for basic implementation – mandatory
data-containernoneany otherid of the div element that will host the display of Virtual Authenticator – mandatory
data-aliasnone-Bookmark ID alias – mandatory
data-actionnoneauthenticationfor users authentication
activationfor users to activate their browser token. They are prompted to enter a secure site ID
pushactivationfor users to activate their browser, with a push notification received on their inWebo registered mobile
unlockfor users to unlock their browser token. Users a prompted to enter an inWebo unlock code to reset their pin code
changepinto allow users to change their pin code
data-nopin01Boolean. If set to 1, authentication without pin is forced
data-silent-run01Boolean. 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-start01Boolean. If set to 1 no splash screen is displayed when Virtual Authenticator loads
data-langauto“fr” or “en”Sets the language of Virtual Authenticator interface. Default value “auto” means that the user's preferred langage is used.
data-usekeypad10Boolean. If set to 0 Virtual Authenticator is displayed without the virtual keypad
data-widthautoString. 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 (useful in two-step auth scenarios)

Code Block
languagexml
<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 secure site id field during activation)

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



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 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”.

Code Block
languagexml
  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:

Code Block
languagexml
  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.

Code Block
languagexml
    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:

Code Block
languagexml
    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:

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


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

Code Block
languagexml
  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:

Code Block
languagexml
    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):

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

Typical handling of a successful activation:

Code Block
languagexml
    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

Code Block
languagexml
    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>)

Code Block
languagexml
<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>):

Code Block
languagexml
<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.


Panel
borderColor#C5C5C5
borderWidth1

Table of Contents
stylesquare

Updated on 01/15/2017