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.

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.

  • device.type: The device type, as returned by the PingID SDK Server. Possible values: Android, iPhone, SMS, Email.

  • device.label: The device nickname.

  • device.subLabel:

    • Android, iPhone: The device name, as returned by the PingID SDK Server.
    • SMS: The country code and the phone number (format: <<>> <<>>).
    • Email: The email address.
  • device.maskedSubLabel: A masked subLabel.

    • SMS, Email: Only part of the SMS/email is visible.
    • Android, iPhone: The subLabel appears, and there is no masking.
  • device.cssStyles:

    • Android, iPhone: device mobile-phone.
    • SMS: device SMS.
    • Email: device email.
  • 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
  • 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

    In order to change a device, the following URL should be used:

    $resumePath?change_device=1

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

    This URL can be used even if $changeDevice is not set to True.

    However, note that if the admin configuration doesn’t permit changing a device, any attempt to change the device will result with an immediate failure.

    There is no benefit from adding a “change device” button when the $changeDevice parameter is False. Therefore, it is recommended to add “change device” buttons only when the $changeDevice parameter is True.

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.

The rejectReason may also be none of the above, with the assumption that new rejectReason 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.

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

HTML template header

<head>
  <title>$messages.getMessage("pingid.sdk.title.$status")</title>
  <base href="$PingFedBaseURL" />
  <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="assets/pingid-sdk/js/functions.js"></script>
  <link rel="stylesheet" media="all" type="text/css" href="assets/pingid-sdk/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.
base href $PingFedBaseURL points to the resume path URL.
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 way the HTML page is loaded, depends on the status (in this template).

If the status is “in_progress”, a javascript method is called (“startAuthenticating”).

There is a 3 seconds delay from the adapter response until the next polling request.

The delay duration is configurable (the POLLING_DELAY variable in functions.js)

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.

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

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

The delay time is configurable (the FINALIZE_DELAY parameter).

If showAndContinue is 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.

Note: After modifying the functions.js file, end-users will have to delete their browser cache in order to see the changes that have been made. It’s highly recommended to make all of the desired changes to the functions.js file before deployment.

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

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:

#authentication messages

# appears when sending sms to the user (authentication)
pingid.sdk.authentication.sms.message=Your authentication passcode is: ${otp}
# appears when sending sms to the user for new device approval
pingid.sdk.authentication.sms.message.new.mobile.access=New Device Access: ${device_name} ${device_type}. Your pairing code is: ${otp}

#!!!note!!! alphanumeric sender id is not supported in many countries. Read here: https://support.twilio.com/hc/en-us/articles/223133767-International-support-for-Alphanumeric-Sender-ID
#uncomment the sender id message key if you wish to use it
#pingid.sdk.authentication.sms.sender=

#email locale & email configuration type must be filled if Email is enabled as authentication method
pingid.sdk.authentication.email.locale=en
#the following are examples of email configuration types:
# pingid.sdk.authentication.email.configuration.type is the pre-defined email authentication configuration
# pingid.sdk.authentication.email.new.mobile.access.configuration.type is the pre-defined email authentication configuration when a new mobile device accesses
# Note: these configurations types are examples. You need to create configuration types for your applications and set the names here 
pingid.sdk.authentication.email.configuration.type=auth_without_payload
pingid.sdk.authentication.email.new.mobile.access.configuration.type=auth_with_payload


#uncomment this message key if you wish to customize the push title
#pingid.sdk.authentication.push.title=

#uncomment this message key if you wish to customize the push body
#pingid.sdk.authentication.push.body=

#uncomment this message key if client context is supported
#pingid.sdk.authentication.client.context=