Advanced CIBA prompt customizations

Advanced prompt customizations allow for complex and programmatic attribute mappings. These customizations can require coordinated changes in several locations.

Overview

Advanced prompt customizations are made possible using the PingOne Template Variables table on the Instance Configuration tab of the PingOne MFA CIBA Authenticator configuration. The two columns behave as follows:

PingOne Template Variable Name

Allows you to define an attribute name.

When the authenticator passes this attribute to PingOne, it becomes available to use as a dynamic variable in the PingOne notification template. For example, the attribute purchaseTotal becomes accessible in PingOne as the dynamic variable ${purchaseTotal}.

PingOne Template Variable Value

Allows you to combine or manipulate a variety of inputs to create a dynamic value for the attribute.

You can use Apache Velocity Template Language code in this field. For more information on working with Velocity Template Language, see Velocity Template Language in the Apache documentation.

This field is the core of the advanced prompt customizations. The sections below describe the various inputs that you can use in this field.

You will need to coordinate these changes in the following locations:

PingOne notification templates
- Use the variables that you define in the PingOne Template Variable Name field.
PingOne CIBA MFA Authenticator Extended Contract tab
- Add any CIBA request policy attributes that you use in the PingOne Template Variable Value field.
PingFederate CIBA request policy
- Modify the Contract Fulfillment tab to provide the request policy attributes that you use in the PingOne Template Variable Value field.

The sections below describe the types of inputs and techniques that you can use in the PingOne Template Variable Value field. The examples show the coordinating changes that you need to make.

Contract attributes from the CIBA request policy

If your CIBA request policy includes valuable contract attributes that you want to include in the CIBA prompt, you can include the attributes in the PingOne Template Variable Value field.

To make an attribute available in the PingOne Template Variable Value field, add it on the Extended Contract tab of the authenticator configuration.

If your CIBA request policy does not already include an attribute that you want to use, configure it on the Contract Fulfillment tab of your CIBA request policy.

For example, if you wanted to combine plain text and two request policy attributes to create a purchase summary, you would to the following:

In the PingOne notification template, use this variable:
```
${purchaseSummary}
```
In the PingOne MFA CIBA Authenticator, in the PingOne Template Variables table:
1. In the PingOne Template Variable Name field, enter:
  purchaseSummary
2. In the PingOne Template Variable Name field, enter:
  The purchase total for $subject is: $sum $currency.
In the PingOne MFA CIBA Authenticator, on the Extended Contract tab, add:
- sum
- currency
  
  The subject attribute is in the core contract and does not need to be added.
In the PingFederate CIBA Request Policy, on the Contract Fulfillment tab, map values for the following contract attributes:
- sum
- currency
- subject

In the resulting prompt, the value becomes:

The purchase total for jsmith is: $40 USD.

Language pack messages

Use the $languagePackMessages attribute to include a message from the language-pack file configured for this authenticator. The authenticator includes the message from the language-pack file that matches the user’s locale.

For example, to include a localized warning message in the user prompt, you would do the following:

In the PingOne notification template, use this variable:
```
${localizedTransferWarning}
```
In the PingOne MFA CIBA Authenticator, in the PingOne Template Variables table:
1. In the PingOne Template Variable Name field, enter:
  localizedTransferWarning
2. In the PingOne Template Variable Name field, enter:
  $languagePackMessages.getMessage(“transfer.warning”).

In the resulting prompt, the value becomes:

Advertencia: transferencia de dinero iniciada

For language pack messages, you do not need to add anything to the Extended Contract tab or modify your CIBA request policy.

Although you can localize messages in PingFederate, the PingOne notification templates has built-in localization that is based on the user’s PingOne profile. Also, handling localization in PingOne might provide a more centralized administrative experience.

Modified request context attributes

You can use any attributes contained within the $oobAuthRequestContext sent by the client to PingFederate.

The attributes are flattened and available to use in the following format in the PingOne Template Variable Value field:

$locale – The user’s locale which represents the user’s country and language.
$requestedScope – The descriptive scope name requested by the client, such as "Email address access". Multiple scopes are separated with a new line (\n).
$requestingApplicationId – ID of the requesting client.
$requestingApplicationName – Name of the requesting client.
$requestingApplicationLogoUrl – Logo image URL of the requesting client.
$authUserBindingMessage – A human-readable message or number intended to be displayed on both the consumption device and authenticating device to provide a visual cue of the interaction to the user.

For detailed information about what is available in $oobAuthRequestContext, see Class OOBAuthRequestContext in the PingFederate SDK documentation (Javadoc).

For example, to separate scopes with commas instead of line breaks, you would do the following:

In the PingOne notification template, use this variable:
```
${commaDelimitedScopes}
```
In the PingOne MFA CIBA Authenticator, in the PingOne Template Variables table:
1. In the PingOne Template Variable Name field, enter:
  commaDelimitedScopes
2. In the PingOne Template Variable Name field, enter:
  #set( $delimiter = "")#foreach($scope in $oobAuthRequestContext.requestedScope.values())$delimiter$scope#set( $delimiter = ", ")#end.

In the resulting prompt, the value becomes:

Email address access, Phone number access

For request context attributes, you do not need to add anything to the Extended Contract tab or modify your CIBA request policy.