JavaScript Login Application

Experimental

The JavaScript Login Application is considered an experimental feature. It is prone to change in future releases with no ensured backwards compatibility.

To enable integration of out-of-band login flows, a JavaScript application library needs to be served to browser clients that interact with Nevis Mobile Authentication. Specifically, the component involved in serving the JavaScript library is nevisLogRend.

Setting up nevisLogRend to use the JavaScript login library is an integration task; refer to the Nevis Mobile Authentication Concept and Integration Guide for detailed instructions for out-of-band authentication integration.

Installation

The JavaScript library is installed using the client RPM. After installing the RPM, the JavaScript library is located under /opt/nevisfidocl/nevislogrend/lib/nevisMobileAuthLogin.js.

Configuration

The plug-in offers several configuration options passed at initialization to adjust to project specifics.

Example configuration

authLogin.init({debug: true});

Available configuration options are:

formDomSelector (string, "form [name=oobloginform]") A valid DOM selector of the login form. The plug-in "binds" itself to this form and will only react and initialise if the form is present in the HTML page.

redeemUrlDomSelector (string, "input [name=redeemUrl]") A valid DOM selector of an element with a value attribute containing the URL to the redeem authentication token endpoint. This field is required to display the authentication QR code.

usernameDomSelector (string, "input [name=isiwebuserid]") A valid DOM selector of an element with a value attribute containing the loginId of the user.

submitDomSelector (string, "button [name=submit]") A valid DOM selector for the submit form element.

dispatchTargetsListDomContent (string, <ul id="dispatchTargets"></ul>) A string containing an HTML element which will contain the selection list of dispatch targets (if more than one dispatch target exists for the loginId).

dispatchTargetDomContent (string, <li class="list-group-item list-group-item-action"></li>) A string containing an HTML element which will contain a dispatch target. This element will be rendered into the dispatchTargetsListDomContent element.

qrCodeDomContent (string, <div id="qrCode"></div>) A string containing an HTML element which will contain the authentication QR code.

spinnerDomContent (string) A string containing an HTML element which represents a spinner indicating to the user that an operation is going on in the backend. The default value of this property is:

<div id="spinner" style="padding: 10px">
    <div class="d-flex justify-content-center">
        <div class="spinner-border" role="status" style="width: 8rem; height: 8rem;">
            <span class="sr-only">Loading...</span>
        </div>
    </div>
</div>

statusDomContent (string, <div id="status" class="alert alert-info"></div>) A string containing an HTML element which will contain status information during the login process.

pollingIntervalMs (integer, 500) Value defining the polling interval during the mobile authentication in milliseconds.

dispatchTitle (string, "Nevis Mobile Authentication Login") A string containing the title of the push message sent to the user.

debug (boolean, true) If set to true, additional debug information is logged to the browsers JavaScript console.

renderQRCode (callback, function(data,parentElement)) A function defining how to render the authentication QR code. The function takes the data to be rendered as well as a reference to the DOM element which servers as a container. The default function provided is:

function (data, parentElement) {
  QRCode.toCanvas(data, {
    color: {
      dark: '#047D82',
      light: '#ffffff'
    },
    errorCorrectionLevel: 'M'
  }, function (err, canvas) {
    if (err) {
      throw err;
    }
    parentElement.appendChild(canvas);
  });
}

done (callback, function(form)) A function which will be executed if the authentication finished successfully. The default function provided is:

function (form) {
  window.location.replace(loginForm.getAttribute("action").replace('?login', ''));
}

fail (callback, function(form)) A function which will be executed if the authentication fails.

function (form) {
  updateStatus({status: "failed"});
}

statusMessages (dictionary) This dictionary contains status messages presentable to the user based on backend status reports.

The current plug-in implementation doesn’t support multiple languages

The default dictionary provided is:

{
    dispatchError: "There has been an error upon dispatching the token.",
    dispatchTargetNotFound:
    "No matching target device found, contact support.",
    dispatcherNotFound:
    "No means of sending the message found, contact support",
    internalError: "An unspecified error occurred. Contact support.",
    tokenRedeemed: "The token has been successfully redeemed.",
    tokenTimedOut: "The operation has timed out, retry.",
    tokenCreated: "The login token has been created.",
    clientRegistering: "Unexpected status, this seems to be a registration.",
    clientAuthenticating: "Authenticate in your mobile device.",
    failed: "Login failed.",
    succeeded: "Login successful.",
    unknown: "Unknown token.",
    networkError: "No connection to the backend.",
    noDispatchTargets: "No devices available for authentication."
}

AuthState Configuration Example

The JavaScript plug-in requires some DOM elements to be present in the HTML page to be activated. These elements can be specified in an AuthState using GuiElements. The following sample configuration defines an AuthGeneric AuthState, whose only role is to define the HTML elements to be rendered. This includes the following elements:

• The HTML form, named oobloginform as expected by the JavaScript plug-in.
• A hidden field containing the username, whose value is assumed to have been set previously by another AuthState in the fidocredential.loginid attribute of the session.
• The redeem URL value, which is required by the JavaScript to render the authentication QR code to be presented to the user.
• The submit form element (a button).

<AuthState name="SubmitOutOfBandParameters" class="ch.nevis.esauth.auth.states.standard.AuthGeneric">
    <ResultCond name="default" next="DemoOutOfBandFidoUafAuthState" />
    <ResultCond name="error" next="AuthError" />
    <ResultCond name="failed" next="AuthError" />
    <Response value="AUTH_CONTINUE">
        <Gui name="oobloginform">
            <GuiElem name="isiwebuserid" type="text" value="${sess:fidocredential.loginid}" />
            <GuiElem name="redeemUrl"    type="hidden" value="https://siven.ch/token/redeem/authentication" />
            <GuiElem name="submit"       type="button" label="continue.button.label" value="continue" />
        </Gui>
    </Response>
</AuthState>