PortaSigma Authentication Widget

Codename: portasigma-authenticationwidget

The goal of the authentication widget is to provide a simple mechanism to authenticate users through digital certificate, independing of the browser used. The autentication widget is composed by the elements below:

• Javascript code to read certificates, including a reload option

• Invocation of a filtering process in the server, to select appropriate certificates

• Inclusion of required libraries (e.g. jQuery)

• Presentation and styling (XHTML/CSS)

• Internationalisation

In the documentation below we will refer subsequently to the application that uses the services of the authentication widget as the client, and to the owner of the client application as the customer.

Pre-requisites

Prior to using the authentication widget, you must have a PortaSigma user and request to ISIGMA the widget functionallity. Next, you can obtain an access key from Portasigma API widget method .You have to request this key every time you render the widget.

Basic Usage

The simplest way to include the widget is as an iframe inserted in the pages of the client application:

<iframe
    id="applet"
    frameborder="0"
    src="http://app.portasigma.com/widget/init.html?key=Msh4fllvmK%2Fgb5ZgfyGW&locale=es">
</iframe>

The src attribute is a URL that points to the widget server and includes some parameters, such URL encoded access key. These are described in detail below.

The id is only used as a javascript/css hook, so that you can easily style where/how you want your iframe to appear, i.e.:

#applet {
    position: absolute;
    top: 0px;
    right: 0;
    width: 420px;
    height: 100%;
    border: 0px;
    overflow: hidden;
}

Operation Overview

In the authentication process ,PortaSigma server generates an authentication token, the user signs it with his digital certificate, and finally

The following diagram summarizes the complete widget’s flow of operation, including the client application:

1. The client application generates the start page, that includes the widget’s iframe, that is rendered by the PortaSigma server

2. Once rendered in the user’s browser, the widget will read all of the user’s personal certificates and send them to the PortaSigma server for validation. The server will return a list of the acceptable certificates for this application

3. Once the certificates are displayed, the user may click on one of them. This will generate a signature of the authentication token. This signature is posted to the PortaSigma server for validation

4. The PortaSigma server verifies the signature

5. If the signature is OK, it extracts information from the certificate and display the signer certificate attributes in a result verification template. It the signature verification fails, the verification template will contain the error message.

6. Finally, the verification page issue a Javascript event to the parent page with the signer certificate params and the authentication result in JSON mode. (see Parent Notification)

Parameters

The following are the parameters to the widget.

• key: the access key to securely access to the widget

• locale: the widget language

Parent Notification

Since the widget is displayed within an iframe, all navigation initiated by it will be displayed inside it. At some point (after authentication), we will want to proceed forward to a page that doesn’t contain the iframe and finalize the authentication process retrieving the result. This navigation must be done from the main page, therefore we need to retrieve this parameters.

The mechanism to do this is by retrieving a Javascript event in the parent. In order to achieve this you need:

1. Declare an event listener to catch the result event

2. Parse the JSON received to obtain the authentication result and the signer certificate params

in the parent page we could write:

window.addEventListener('message', widget_notification, false);

     function widget_notification(evt)
     {
             var json =  JSON.parse(evt.data);
             var result = json.result;

             if("error" == result){
                     window.location = "/login-error.php";
             }
             else{

                     var signerCN = json.CN;
                     var signerC = json.C;
                     var signerL = json.L;
                     var serialnumber = json.SERIALNUMBER;
                     var ST = json.ST;

                     window.location = "/login-successful.php?SERIALNUMBER="+serialnumber;
             }
     }

This way,the main page will receive the notification call and proceed to login, refreshing the contents of the full browser page and thus escaping the iframe.