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:

Status Description
in_progress The authentication of the user is in progress.
select_device This may be one of the following:
  • The application’s configuration is set to Device selection mode.
  • The application’s configuration is set to Default to primary. The user has more than one trusted device, but does not have a primary device.
change_device The user chose to change the authenticating device.
approved The authentication of the user or device has been approved
bypassed_device The admin has configured this device to gain access and bypass the MFA requirement.
user_suspended The user is suspended (disabled).
ignored_device The user tried to authenticate from a device that was configured as IGNORED.
rejected The authentication of the user or device has been rejected.
timeout The maximum permitted time for authentication of the user has lapsed, but the user’s device was unreachable, or the user did not react.
canceled The user canceled their authentication attempt before it completed.
error An error occurred during the authentication process.
otp The user should enter a one time passcode.
invalid_otp The user entered a wrong OTP, and is permitted to retry.
locked The user device is locked for a period of time, since the user tried to authenticate offline and entered a wrong OTP in the maximum possible number of attempts.
qr_code The QR code page is rendered.
user_selection The user list is displayed in the following cases:
  • The application that scanned the QR code is shared, and the web selected the users.
  • The PingID SDK adapter was invoked without a given username from the mobile application, and the application is shared.

Velocity parameters

Parameter Description
status This parameter can be one of the values mentioned above. Its value depends on the current state.
csrfToken A token which must be used in each request to the adapter. The adapter creates a new token for each transaction. This token is sent as a velocity parameter.

In order to resume to the adapter, add this parameter in a post request.

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

messages Points to the class, which retrieves a message by key. For example:

$messages.getMessage(“pingid.sdk.select.device.label.select.device”) retrieves the message value by the key pingid.sdk.select.device.label.select.device.

  • By default, it searches the pingid-sdk-messages properties file.
  • The file name is configurable and each adapter can use a different properties file.
  • Each locale should have a unique properties file. For example, the English locale file name (by default) is: pingid-sdk-messages_en.properties.
device Represents a user device.

Appears only if the status parameter is one of the following:

  • in_progress: In this case, the device is the authenticating device.

  • select_device: In this case, the device is an element in the $devices parameter which contains all the user devices.

  • change_device: In this case, the device is an element in the $devices parameter which contains the list of all the user devices.

  • otp: In this case, the device is the authenticating device from which the user should retrieve the one time passcode.

  • invalid_otp: In this case, the device is the authenticating device from which the user should retrieve the one time passcode.

device parameter properties:

  • device.id: The device ID, as returned by the PingID SDK Server.
    • qrCodeId: The device ID, when the authentication method is a QR code.
  • device.type: The device type, as returned by the PingID SDK Server. Possible values: Android, iPhone, SMS, Voice, Email, QrCode.
  • device.label: The device nickname.
    • The text defined in the messages properties file under the key pingid.sdk.qrcode.device.label when the authentication method is a QR code.
  • device.subLabel:
    • Android, iPhone: The device name, as returned by the PingID SDK Server.
    • SMS: The country code and the phone number (format: <<>> <<>>).
    • Voice: The country code and the phone number (format: <<>> <<>>).
    • Email: The email address.
  • device.maskedSubLabel: A masked subLabel.
    • SMS, Voice, Email: Only part of the SMS, voice or email is visible.
    • Android, iPhone: The subLabel appears, and there is no masking.
    • QR code: Undefined.
  • device.cssStyles:
    • Android, iPhone: device mobile-phone.
    • SMS: device sms.
    • Voice: device desk-phone.
    • Email: device email.
    • QR code: device qr-code.
  • device.deviceDetails:
    • The “deviceDetails” property is a reference to the “Device” resource as returned by the PingID SDK Server. Refer to User Devices API. For example:
      • device.deviceDetails.deviceRole
      • device.deviceDetails.osVersion
    • The “deviceDetails” property is undefined for QR code authentication.
changeDevice

Indicates whether changing the device is possible and permitted.

The changeDevice parameter is true only if:

  1. The user has more than one device.
  2. Changing a device is permitted in the admin configuration.
  3. The “status” parameter is one of the following:
    • in_progress (unless this is a silent push)
    • locked
    • timeout
    • canceled
    • otp
    • invalid_otp
    • error, except when $errorReason is one of the following, since in these cases changing the device won’t help the user to authenticate:
      • heartbeatFailure

      • applicationDisabled

      • sessionExpired

      • invalidMobilePayload

      • emailNotEnabled: the changeDevice parameter will be false if all the user’s devices are email devices only.

        In addition, if the error reason is one of the following, the changeDevice parameter will be false if all the user’s devices are SMS devices only:

        • smsQuotaExceeded
        • smsNotEnabled

        Further, if the error reason is one of the following, the changeDevice parameter will be false if all the user’s devices are voice devices only:

        • voiceQuotaExceeded
        • voiceNotEnabled

changedDevice also appears when the status is “qr_code” and the user is known. In this use case, changeDevice appears even if the user has only one device, since the user can choose between QR code authentication or mobile app authentication.

The changeDevice parameter is not permitted if the user is unknown (when the PingID SDK adapter was invoked without a given username).

In order to change a device, the following URL should be used: $resumePath?change_device=1

newDevice Indicates that the page appears when a new mobile application device (unpaired device) accesses.

This parameter is true only with the following status values:

  • select_device: In this case, the user chooses which device should approve the new device access.
  • otp, invalid_otp: In these cases, the user needs to enter the passcode from the authenticating device in order to approve the unpaired device access.
devices List of devices, where each element is a device as explained above.
  • Appears only when status is: change_device or select_device.
  • The order is the same order as the list returned by the SDK Server, which means you cannot assume anything about the order.
  • You can change the order by using javascript.
  • By default, the selected device is the first device. This behavior can also be changed by using javascript.
rejectReason Appears only if the status is rejected.

rejectReason can be one of the following:

  • unabledToAutoPairFromWeb: When automatic pairing is supported, and a user authenticates from the web and the admin configured blocking users in this scenario (PingFederate admin console: Identity Provider > Adapters > PID SDK Adapter > IdP Adapter > UNPAIRED USERS - WEB LOGIN -> Block User - Require Pairing).
  • inactiveUser: When automatic pairing is not supported and an inactive user authenticates, and the admin configured blocking users in this scenario. (PingFederate admin console: Identity Provider > Adapters > PID SDK Adapter > IdP Adapter > UNPAIRED USERS - MANUAL PAIRING -> Block User - Require Pairing).
  • blockedByUser: The user authenticates with an unpaired device and the authenticating device blocks access.
  • deviceIsBlocked: The user authenticates with an unpaired device which is blocked. The difference between “blockedByUser” and “deviceIsBlocked” is that the latter refers to a scenario is which the device is already marked as “blocked” by the admin or in previous authentications of this device.
  • authenticationTokenExtraPushNotificationFailed: The user scanned the QR code. However, the extra push verification failed. This occurs when the push failure is defined as “Regard as failure” in the PingFederate adapter configuration.
  • deviceIsRooted: The user device has been detected as rooted or jailbroken.

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

rootedDevice A device type object, that appears only if the status is "rejected" and rejectReason has a value of "deviceIsRooted".
approvedReason Appears only if the status is approved.

approvedReason can be:

  • authenticationToken: The user approved the authentication after scanning the QR code or clicking the deep link.

approvedReason will not be set in any other case.

New approvedReason values can be added in the future.

cancelReason Appears only if the status is canceled.

cancelReason can be one of the following:

  • deniedByUser: If the user received a push to the mobile during authentication and chose to deny it.
  • canceledByUser: If the user received a push to the mobile during authentication and chose to cancel the authentication.
  • authenticationToken: The user denied the authentication after scanning the QR code or clicking the deep link.

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

errorReason Appears only if the status is error.

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.

resumePath The resume URL path. Each call from the HTML or javascript should use the given resumePath, with the necessary parameters, if relevant.

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

adapterId The adapter ID, as configured in the adapter configuration. It is useful when there are minor changes between adapters, and the same HTML can be used, rather than using different HTML template files. showAndContinue This parameter is true if the status is considered as a “success” status. Currently, the following statuses are considered as success:
  • 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.

users

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:

Parameter Description
grayQRCodeImg The QR code image has a gray foreground on a white background.
  • This is the default setting in the HTML template.
  • Comment this entry and uncomment the "blackQRCodeImg" entry to change the QR code image to display black on a white background.
blackQRCodeImg The QR code image has a black foreground on a white background.
  • By default this setting is inactive, and appears in the HTML template as a comment.
  • Comment the "grayQRCodeImg" entry and uncomment this entry to change the QR code image to display black on a white background.
useDeepLink True, if the browser was launched from a mobile. In this case, the user will see first the "deep link" page. The user will be able to switch to the QR code image page. In this case, the "back" link will be displayed, which will enable the user to switch back to the deep link view.
userExists True, if the user is known, for example, if the user entered a username and password in previous adapter.
changeDevice True, if it is possible for the user to change the device.
changeDevice will not be appear if the user is unknown.
mobileAccessFlow Set to true or false in the user selection page.

There are 2 scenarios in which the user selection page is displayed:

  1. The mobileAccessFlow parameter is false.

    • The device that scans the QR code is shared, and the QR code was created with “web user selection” option on. The default is that the mobile application selects the users.
    • In this case, the “user selection” page replaces the QR code page.
    • Then, a javascript function polls until the QR code is expired (3 minutes), or until the user selects a user from the list.
  2. The mobileAccessFlow parameter is true.

    • A trusted mobile device accesses with a payload, the device is shared, and the user is unknown.
    • There is no polling in this case.

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

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>

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>
Parameter Description
title In this template, the HTML page title depends on the current status. For example, if the current status is approved, the pingid.sdk.title.approved key will be used to retrieve the title text.This behavior is configurable.
script This template uses the functions.js file, which contains a few javascript methods.
CSS This template uses the main.css file.

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:

Variable Description
POLLING_DELAY The interval between successive polling requests until the current authentication status is returned.
It commences with user authentication, and continues until the user approves or denies the authentication request, or until a timeout occurs.
Default: 3 seconds.
QR_CODE_POLLING_DELAY The interval between successive QR code polling requests.
Once the QR code is rendered, or a link appears in case of mobile access, a JavaScript function polls PingFederate to retrieve the current QR code status. If the QR code has expired, it is automatically refreshed.
Default: 3 seconds.
QR_CODE_POLLING_USER_SELECTION_DELAY The interval between successive polling requests, when a user list is presented after a QR code is scanned.
In this case, polling is executed in order to ensure that the QR code is not expired or canceled.
Both the following conditions must apply:
  • The device which scanned the QR code is paired with multiple users.
  • The QR code was created using the “web user selection” option. (The default is that the mobile application selects the users.)

Default: 3 seconds.
FINALIZE_DELAY The duration of time that a success, failure or timeout screen will be displayed.
Default: 2 seconds.

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