Customizable user-facing pages
PingFederate supplies HTML templates, located in the <pf_install>/pingfederate/server/default/conf/template
directory, to provide information to the end-users or to request user input when processing their requests.
The PingFederate HTML templates utilize the Velocity template engine, an open-source Apache project. For more 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. CSS 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 and Usage | ||
---|---|---|---|
utils- utility class |
The utility method to display JSON String arrays. |
||
$escape |
A utility class that can be used to escape String variables inserted into the template, such as Use
|
||
$HttpServletRequest |
A Java object instance of |
||
$HttpServletResponse |
A Java object instance of |
||
$locale |
A Java object instance of |
||
$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, use the $CurrentPingFedBaseURLvariable instead of the $PingFedBaseURL variable. |
||
$templateMessages |
Used to localize messages in the template, based on user’s Locale, an instance of |
||
$TrackingId |
The user’s session tracking ID. |
The following describes variables that are available on some templates.
Variable | Description |
---|---|
$entityId |
The entity ID (connection ID) of the SP connection used in this SSO transaction. |
$connectionName |
The name of the SP Connection used in this SSO transaction. |
$client_id |
The ID of the OAuth client used in this transaction. |
$spAdapterId |
The SP Adapter ID used in this transaction. |
$baseUrl |
The base URL of PingFederate instance. |
$adapterId |
The IdP Adapter ID used in this transaction. |
$oidcUiLocales |
The value of the OpenID Connect |
$extendedProperties |
The extended properties defined on either the connection or OAuth client. |
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 a single sign-on (SSO) error occurs during identity provider (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 single logout (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 SP Default URLs window (Applications → Integration → SP Default URLs) or the IdP Default URL window (Authentication → Integration → IdP Default URL).
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 can also localize these messages using the PingFederate localization framework.
If you have a clustered PingFederate environment, copy the customized, and localized, templates to each node. |