Configure HTML login template

The PingID SDK Adapter uses a default HTML template: pingid.sdk.login.template.html.

The admin can change the HTML template’s file name in the adapter configuration. Please refer to the documentation describing the adapter creation and configuration.

The adapter template uses the Apache Velocity Engine ( http://velocity.apache.org/engine/1.7/user-guide.html).

The default template is divided into blocks (sections).

Each block is rendered according to the current status:

#if($status == "in_progress")
	"In Progress" HTML Section
#elseif($status == "select_device")
	"Select Device" HTML Section
#elseif( . . .)
	...
. . .
#end

Only one section is rendered at a time, and the other sections are not rendered.

Possible statuses:

Velocity parameters

The cancelReason may also be none of the above, with the assumption that new cancelReason values can be added in the future.

errorReason can be one of the following:

• sessionExpired: The PingID SDK session expired.
• smsQuotaExceeded: The daily SMS quota was exceeded.
• smsNotEnabled: The user attempted to authenticate with SMS, and SMS is disabled.
• voiceQuotaExceeded: The daily voice quota was exceeded.
• voiceNotEnabled: The user attempted to authenticate with voice, and voice is disabled.
• emailNotEnabled: The user attempted to authenticate with Email, and Email is disabled.
• deviceBlocked: The automatic pairing failed since the device is blocked. Only relevant when the user is inactive or when the pairing is done without the device network (each device is paired separately).
• applicationDisabled: The application is disabled.
• heartbeatFailure: The PingID SDK Service is unavailable.
• invalidMobilePayload: Whenever the mobile payload is invalid.

Based on the assumption that new errorReason values may be added in the future, the errorReason may also be none of the above listed values.

Note: If the csrfToken is not part of the request, a new user session is initiated.

• approved
• bypassed_device
• ignored_device

The template uses this value in order to display the screen for few seconds (configurable), and then resumes to the adapter.

An array of the users.
Each element has the form of:

{“username” : “<username>”, “firstName”: “<firstName>”, “lastName”: “<lastname>”, “status”: “<status>”. “displayName”: “<displayName>”}

• username: The username, as stored on the PingID SDK Server.
• firstName:- The user’s first name, as stored on PingID SDK Server.
• lastName: The user’s last name, as stored on PingID SDK Server.
• status: The user’s status, as stored on PingID SDK Server.
• displayName: Has one of the following values:
  • Both the firstName and lastName when both have values, in the form “firstName lastName”. For example: “Eric Jones”.
  • The username, if both firstName and LastName are empty. For example: “ericj@moderno.com”.
  • The lastName, if the firstName is empty. For example: “Jones”.
  • The firstName, If the lastName is empty. For example: “Eric”.

For example:
"{“username” : “ericj@moderno.com”, “firstName”: “Eric”, “lastName”: “Jones”, “status”: “ACTIVE”. “displayName”: “Eric Jones”}

The users velocity parameter is set when the status is: user_selection.

QR code velocity parameters

The following velocity parameters may apply in cases of authentication using QR code:

QR code page

The QR code page is rendered when the velocity parameter status is “qr_code”. This page is divided into the following two subpages.

• QR code image page
• QR code deep link page

QR code image page

This page displays the QR Code image.

Velocity parameters used in the QR Code image page:

• $grayQRCodeImg (default)
• $blackQRCodeImg
• $useDeepLink
• $userExists
• $changeDevice

It is possible to cancel the QR code.
By default, the CANCEL button is commented. Uncomment the line to use the cancel option.
When the user clicks the CANCEL button, the policy.action contract attribute is populated with “canceled” (which is configureable) and the adapter returns the “ACTION” status.
You can configure the policy flow to direct the user to another adapter.
The policy action can be changed in the HTML template. For example:

<form id="cancelQRCodeForm" name="cancelQRCodeForm" action="$resumePath?cancel=1&action=canceled" method="post">
  <input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/>
</form>

QR code deep link page

This page is displayed if the browser was launched from a mobile device.

Velocity parameters used in the deep link page:

• $userExists
• $changeDevice

It is possible to cancel the QR code.
By default, the CANCEL button is commented. Uncomment the line to use the cancel option.
When the user clicks the CANCEL button, the policy.action contract attribute is populated with “canceled” (which is configureable) and the adapter returns the “ACTION” status.
You can configure the policy flow to direct the user to another adapter.

HTML template header

<head>
  <title>$messages.getMessage("pingid.sdk.title.$status")</title>
  <meta name="robots" content="noindex, nofollow" />
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta name="viewport" content="initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
  <script src="/pingid-sdk-web/js/functions.js"></script>
  <link rel="stylesheet" media="all" type="text/css" href="/pingid-sdk-web/css/main.css" />
</head>

HTML template body tag

#if($status == "in_progress")
<body onload="startAuthenticating(&quot;$resumePath&quot;, &quot;$csrfToken&quot;)">
#elseif($status == "select_device" || $status == "change_device")
<body onload="initializeSelectDeviceBlock()">
#elseif($showAndContinue)
<body onload="finalize()">
#else
<body>

The template’s status determines the way the HTML page is loaded.

• “in_progress”:
  If the status is “in_progress”, the “startAuthenticating” javascript method is called.
  There is a 3 seconds delay (default) from the adapter response until the next polling request. See Delay control variables for further details.
  The polling continues until the adapter returns a status which is different from “in_progress”. Once the returned status which is different from "in_progress", the polling method posts a hidden form.
  The adapter, in turn, will render a new HTML page according to the new status.

• “select_device” or “change_device”: If the status is: “select_device” or “change_device”, the “initalizeSelectDeviceBlock” javascript method is called.
  This method initializes the device list, and binds the “onclick” event for each row in the list.

• “showAndContinue”:

  • True whenever the user authorization is successful for any reason.
    The template uses this value in order to display the screen for few seconds and then resumes to the adapter.
  • False: The page will be displayed without resuming back to the adapter.

This behavior is configurable by its nature. You can decide which “onload” function (if any) will be executed according to the status, or any other parameter.

Delay control variables

The following variables in functions.js control the duration of delays between polling events, and are configurable:

HTML template loading page

The loading page is displayed when all the following conditions are true:

• The PingID SDK server is not available.
• The current page is the QR code page or the user selection page.
• The user is unknown.

The loading page contains a CANCEL button, which is commented by default.
Uncomment the CANCEL line to permit the user to cancel the QR code. The CANCEL button will appear on the loading page below the loading message (“One moment please…”), as follows:

When the user clicks the CANCEL button, the policy.action contract attribute is populated with “canceled” (which is configureable), and the adapter returns the “ACTION” status.
You can configure the policy flow to direct the user to another adapter.

Once the connection to the PingID SDK server is established, the “One moment please…” message disappears, and the QR code page or the user selection list are displayed.

The loading page is not displayed if the user is known. In this case, the “Authentication during errors” policy is used.

HTML status sections

The HTML template renders each section according to the $status parameter.

1. You can add a “change device” button by using the URL: "$resumePath?change_device=1", for example:

   #if($changeDevice)
   <a class="button" onclick="changeDevice(this)" href="javascript:void(0);">//Enter the name of the button/message properties file index here//For example: pingid.sdk.timeout.button.change.device
   </a>
   #end

   • Note : If the csrfToken is not part of the request, a new user session is initiated.
   • However, note that the parameter “$changeDevice” will be set to true only when the page fits this behavior and if the user has more than one device. You can add a “change device” button even if this parameter is false (not recommended).
   • “change_device” will be false if the user is unknown.

2. You can add a “retry” button by using the URL: $resumePath?retry=1, for example:

   <a class="button" onclick="onLinkClick(this);document.retryForm.submit();" href="javascript:void(0);">//Enter the name of the button/message properties file index here//For example: pingid.sdk.timeout.button.retry
   </a>

   • Note : If the csrfToken is not part of the request, a new user session is initiated.
   • Pressing “Retry” during authentication is not supported.
   • If a certain device was used in the previous authentication attempt, retrying will use the same device.
   • “Retry” is not supported in the QR code page.

3. You can add a “cancel” button for QR code authentication. By default, the “cancel” option is commented in the HTML template. Uncomment the line, to use the “cancel” option. When the user clicks on the “cancel” button, the policy.action contract attribute is populated with “canceled” (configureable), and the adapter returns the “ACTION” status. By default, the policy action is “canceled”. The policy action may be changed in the HTML template as follows:

   <form id="cancelQRCodeForm" name="cancelQRCodeForm" action="$resumePath?cancel=1&action=canceled" method="post">
   <input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/>
   </form>

   • Note : If the csrfToken is not part of the request, a new user session is initiated.
   • From PingFederate 9.2 and later, the HTML Form adapter supports the option of authentication with user credentials or QR code. The admin can configure the policy tree in a way that the user can return to the HTML Form adapter.

4. The template is rendered as a “dead end” in all the scenarios except success authorization. You can change that by adding a “continue” button by using the URL: $resumePath or by rendering the page for some time and then call $resumePath, for example:

   <a class="button" onclick="onLinkClick(this);document.finalizeForm.submit();" href="javascript:void(0);">//Enter the name of the button/message properties file index here//For example: pingid.sdk.timeout.button.continue
   </a>

   • Note : If the csrfToken is not part of the request, a new user session is initiated.

For example, this is how the sample treats each of the above options:

<form id="finalizeForm" name="finalizeForm" action="$resumePath" method="post">
 	<input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/>
</form>

<form id="changeDeviceForm" name="changeDeviceForm" action="$resumePath?change_device=1" method="post">
 	<input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/>
</form>

<form id="retryForm" name="retryForm" action="$resumePath?retry=1" method="post">
 	<input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/>
</form>

<form id="cancelQRCodeForm" name="cancelQRCodeForm" action="$resumePath?cancel=1&action=canceled" method="post">
 	<input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/>
</form>

<form id="systemErrorForm" name="systemErrorForm" action="$resumePath?systemError=1" method="post">
 	<input type="hidden" name="csrfToken" id="csrfToken" value="$csrfToken" encode="false"/>
</form>

Messages File configuration

The messages which appear in each adapter HTML template are located in messages files per locale.

Each locale should have a unique properties file. For example, the English locale file name (by default) is: pingid-sdk-messages_en.properties.

In addition to the template messages, this file contains messages which are relevant to the adapter logic.