PingFederate Server

Customizable email notifications

PingFederate delivers messages to administrators and end-users based on customizable notification publisher settings.

Each component that is capable of triggering or handling events can use a different notification publisher instance to deliver its messages. For example, you can select an SMTP Notification Publisher instance to deliver messages to your end users in an HTML Form Adapter instance and another SMTP Notification Publisher instance to deliver licensing messages to your fellow administrators.

When a component is configured to deliver its messages based on an SMTP Notification Publisher instance configuration, PingFederate creates notification messages based on template files located in the <pf_install>/pingfederate/server/default/conf/template/mail-notifications directory. Each template file is a combination of variables and HTML codes. You can modify these template files in a text editor to suit the particular branding requirements, as needed.

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. $utils.toJsonArray(Collection<Object>) - Use this method to convert a collection into a JSON string.

$escape

A utility class that can be used to escape String variables inserted into the template, such as $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, such as window.location.replace("$escape.forJavaScript($wreply)") as seen in the sourceid-wsfed-idp-signout-cleanup-template.html template file.

Use 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, such as the User-Agent HTTP header.

$HttpServletResponse

A Java object instance of javax.servlet.http.HttpServletResponse. Used to modify the response in the template, such as 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, use the $CurrentPingFedBaseURLvariable 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.

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 ui_locales parameter that conveys the user’s preferred languages and scripts for the user interface.

$extendedProperties

The extended properties defined on either the connection or OAuth client.

$userAttributes

The user-specific data, such as the user’s display name or email address, retrieved from the password credential validator (PCV) used in this transaction.

$grantAttributes

The attributes of the grant used in this transaction.

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

You can also configure a component to use an Amazon SNS Notification Publisher instance to deliver notification messages. If so, refer to Configuring an Amazon SNS Notification Publisher instance and Event types and variables for more information about this messaging model and the handling of notification messages.