PingFederate supplies HTML templates to provide information to the end users or to request user input when processing their requests. These template pages are located in the <pf_install>/pingfederate/server/default/conf/template directory. They utilize the Velocity template engine, an open-source Apache project. For information about Velocity, please refer to the Velocity project documentation on the Apache website at https://velocity.apache.org.

You can modify most of these pages in a text editor to suit the particular branding and informational needs of your PingFederate installation. Cascading style sheets and images for these pages are included in the template/assets subdirectory. Each page contains both Velocity constructs and standard HTML. The Velocity engine interprets the commands embedded in the template page before the HTML is rendered in the user's browser. At runtime, PingFederate supplies values for the Velocity variables used in the template.

Each template contains specific variables that can be used for rendering the associated web page. You can see the variables and usage examples in the comments of each template. The following table describes variables that are available across all templates.

Variable Description
$escape A utility class that can be used to escape String variables inserted into the template; for example, $escape.escape($client.name) where $client.name is one of the variables available in the oauth.approval.page.template.html template file.

Use $escape.forJavaScript($variable) when passing String variables into a JavaScript code block or an event handler within a template; for instance, window.location.replace("$escape.forJavaScript($wreply)") as seen in the sourceid-wsfed-idp-signout-cleanup-template.html template file.

Important:

We recommend using the $escape variable to escape external data, such as request parameters, to mitigate the risk of potential cross-site scripting (XSS) attacks.

$HttpServletRequest A Java object instance of javax.servlet.http.HttpServletRequest. Used to add additional knowledge about the request that is otherwise unavailable in the template (for example, the User-Agent HTTP header).
$HttpServletResponse A Java object instance of javax.servlet.http.HttpServletResponse. Used to modify the response in the template (for example, setting additional browser cookies).
$locale A Java object instance of java.util.Locale that represents a user's country and language. Used to customize the end-user experience. For example, the locale is used to display content in the user's preferred language.
$CurrentPingFedBaseURL The host name found in the request, provided that it matches either the PingFederate's base URL or one of the configured virtual host names.
$PingFedBaseURL The PingFederate base URL.

For most deployments, we recommend using the $CurrentPingFedBaseURL variable instead of the $PingFedBaseURL variable.

$templateMessages Used to localize messages in the template (based on user's Locale), an instance of com.pingidentity.sdk.locale.LanguagePackMessages. For more information, see the Javadoc for the LanguagePackMessages class in the directory <pf_install>/pingfederate/sdk/doc.
$TrackingId The user's session tracking ID.
Important:

Changing Velocity or JavaScript code is not recommended.

At runtime, the user's browser is directed to the appropriate page, depending on the operation being performed and where the related condition occurs. For example, if an SSO error occurs during IdP-initiated SSO, the user's browser is directed to the IdP's SSO error-handling page.

Applications can override the PingFederate server-hosted pages provided specifically for SSO and SLO errors by specifying a URL value in the relevant application endpoint's InErrorResource parameter. Administrators can override SSO and SLO success pages by specifying default URLs on the Identity Provider or Service Provider menu.

The Velocity templates retrieve titles and other text from a message-property file, pingfederate-messages.properties, located in the <pf_install>/pingfederate/server/default/conf/language-packs directory. You may also localized these messages using the PingFederate localization framework.

Note:

If you have a clustered PingFederate environment, copy the customized (and localized) templates to each node.