Transaction approval setup

Transaction approval requests allow you to require authentication for certain actions, such as sending a money transfer or accessing a high-security resource. The PingOne MFA IdP Adapter allows PingFederate to trigger transaction approval requests using PingOne MFA.

To enable this feature, complete the steps in MFA setup, and then use this as a guide to pass transaction approval parameters to the adapter.

You can use the same adapter instance for both the MFA and transaction approval flows, but you’ll need a separate notification template variant for each flow. Create the variants in PingOne.

Overview

For all flow types, the PingOne MFA IdP Adapter passes a set of parameters to PingOne. These parameters indicate which notification template PingOne should use, and provide the values for the variables used in that template.

The only difference between the multi-factor authentication (MFA) and transaction approval flow is the attributes that the adapter receives. For MFA flows, these parameters are provided automatically. For transaction approval flows, you must pass the parameters into the PingOne MFA IdP Adapter.

The following sections describe the PingOne notification templates, the parameters that the adapter collects, and the sources that it collects those parameters from.

Variants for PingOne notification templates are only available through the PingOne API at this time.

PingOne notification templates

A PingOne notification template controls the presentation of the transaction approval request. These templates combine customizable text and variables to form the message that the user sees. For details, see Notification templates in the PingOne documentation.

We recommend that you create a variant of the default PingOne "transaction" template. For example, if you wanted to trigger an authentication challenge for money transfers, you could create the template as follows:

Template type

Transaction

Template variant

Money transfer

Subject

Confirm your money transfer

Body

Enter ${otp} to confirm your transfer of ${sum} ${currency} to ${recipient}.

With the variable values populated, the example template might read as follows:

Confirm your money transfer
Enter 454879 to confirm your transfer of $40 USD to jsmith@example.com.

The ${otp} variable is required for the SMS and Email versions of the transaction template, but all other variables and text are completely customizable. The only requirement is that PingOne must receive a value for each variable that you include.

Transaction approval parameters

For all flow types (including MFA, transaction approval, and CIBA), the PingOne MFA IdP Adapter passes a set of parameters to PingOne. These parameters indicate which notification template to use, and provide the values for the variables used in those templates.

For MFA flows, these parameters are provided automatically. For transaction approval flows, you must pass the parameters into the PingOne MFA IdP Adapter.

The parameters are structured as follows:

pi.template.name

PingOne uses this parameter to determine which notification template to use.

To trigger PingOne to use the "transaction" notification template, this value must be transaction.

pi.template.variant

PingOne uses this parameter to determine which variant of the notification template to use.

For example, if you created a "Money transfer" variant of the transaction template, this value would be money_transfer.

pi.template.locale

Use pi.template.locale to specify the language to use for notifications, for example, fr-CA.

pi.template.variables.<variable_name>

PingOne uses these parameters to populate variables (other than ${otp}) in the transaction template. How you use these parameters depends on the design of your transaction template.

For example, if you make a pi.template.variables.recipient parameter available to the adapter, PingOne will use its value to replace ${recipient} in your transaction template.

pi.clientContext.<variable_name>

When the transaction is initiated by a mobile app with the embedded mobile SDK, PingOne makes these parameters available to the mobile app. How you use these parameters depends on the design of your mobile app.

For example, you could use a pi.clientContext.alert.message parameter to provide the mobile app with text for an alert.

After the PingOne MFA IdP Adapter collects values for these parameters, it creates a JSON object with the following structure:

"pi.template": {
  "name": "transaction",
  "variant": "money_transfer",
  "variables": {
    "sum": "1,000,000",
    "currency": "USD",
    "recipient": "Charlie Parker"
  }
},
"pi.clientContext": {
  "alert.message": "Confirm your money transfer"
}

This JSON object is included in a request that the adapter makes to PingOne.

Parameter sources

The adapter collects values from the following sources:

Chained attributes passed through the PingFederate authentication policy
Tracked parameters in the PingFederate authentication policy
Signed object requests made as part of the OpenID Connect flow from the client application to PingFederate

You can provide parameters to the PingOne MFA IdP Adapter in any grouping you want:

A complete set of parameters (as shown in the JSON object in the previous section)
Several groups of parameters
Individual parameters

In any case, the adapter collects parameters from all sources and merges them into a single complete JSON object to send to PingOne.

If conflicting parameters are provided by more than one source, each of the following sources takes precedence over the ones below it:

Chained attributes
Signed object requests
Tracked parameters

Providing parameter values using chained attributes

You can provide some or all parameters as chained attributes in the PingFederate authentication policy.

For example, you can extend the HTML Form Adapter contract to provide a single parameter, such as pi.template.variables.recipient. Your adapter contract mapping determines the value, such as Charlie Parker.

This screenshot shows the Extended Contract tab of the HTML Form Adapter instance configuration. The pi.template.variables.recipient attribute has been added.

Alternately, you could extend the HTML Form Adapter contract to provide the pi.template parameter with a collection of values in it as JSON object.

This screenshot shows the Extended Contract tab of the HTML Form Adapter instance configuration. The pi.template attribute has been added.

Your adapter contract mapping determines the value. In this example, you could populate pi.template with a JSON object, such as:

{
  "name": "transaction",
  "variant": "money_transfer",
  "variables": {
    "sum": "1,000,000",
    "currency": "USD",
    "recipient": "Charlie Parker"
  }
}

You do not have to map the chained attribute into the PingOne MFA IdP Adapter in your authentication policy.

Providing values in a signed request object

In an OpenID Connect (OIDC) request from your client to PingFederate, you can provide some or all values in the body of the signed request object.

In the following example, the client has provided a complete set of parameters:

https://pf_host:pf_port/as/authorization.oauth2?client_id=ac_oic_client
  &response_type=code
  &scope=openid
  &state=1553ba67-3f92-4768-a3c3-669d0a562d75
  &request=eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJhY19vaWNfY2xpZW50IiwiYXVkIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6OTAzMSIsImNsaWVudF9pZCI6ImFjX29pY19jbGllbnQiLCJyZXNwb25zZV90eXBlIjoiY29kZSIsInNjb3BlIjoib3BlbmlkIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6OTAzMS9PQXV0aFBsYXlncm91bmQvYXV0aG9yaXphdGlvbl9jb2RlL29pZGMvY2FsbGJhY2siLCJzdGF0ZSI6ImMyOGFiNzY1LTgzZjYtNGIzZC05ZjQ5LTZlYzQyNjEwYjg4OCIsInBpLnRlbXBsYXRlIjp7Im5hbWUiOiJ0cmFuc2FjdGlvbiIsInZhcmlhYmxlcyI6eyJzdW0iOiIxLDAwMCwwMDAiLCJjdXJyZW5jeSI6IlVTRCIsInJlY2lwaWVudCI6IkNoYXJsaWUgUGFya2VyIExlIGNhZsOpIFVuZSBmw6p0ZSJ9fX0.IvY5VGRlK90_2k8ZVyI1CfJIudlKaKd5OBmfJCEzgGnEZ0eFbL2sKoh1QSPpYGXkXfj1OFgm2cy0LfnHqeOgTKzEcrOTQIN6mCB9n4aVCWpXNxZvn-VR7a_FaM2_1eUkjoMwLQWGWfWb0Ao-4tpDFqWPFWcdY5Su8G494tl4iQirz1DzX2yjExWO_uBkFj0y3CmDad1mBK7kWfxhkpuUHwdn74tYLcd0g1uWGbVMqRRdBCvB26O1sLIxtb2laEUAx6_Z9m3qRa7qIJWQUBYXY3tCUmg1oPwwsYEY5xgJBNK6lWFNxu1DT7Sq0qDbUlKaHat7pd6C6vRjcd-xwCZL6Q
  &redirect_uri=https://pf_host:pf_port/OAuthPlayground/authorization_code/oidc/callback

The decoded body of the signed request object above is:

{
  "aud": "https://auth.pingone.com/{envId}/as",
  "iss": "{applicationId}",
  "pi.template": {
    "name": "transaction",
    "variant": "money_transfer",
    "variables": {
      "sum": "1,000,000",
      "currency": "USD",
      "recipient": "Charlie Parker"
    }
  },
  "pi.clientContext": {
    "alert.message": "Confirm your money transfer"
  }
}

In this example, the adapter has everything required to send the request to PingOne. It will still collect any available parameters from other sources and merge them into the JSON object provided by the client.

The adapter processes parameter values that are formatted as JSON objects, shown in the example above, or JSON strings.

Providing parameter values using query parameters

In an HTTP request to PingFederate, you can provide some or all parameters using request parameters.

In the following example, only the pi.template.variables.sum and pi.clientContext.alert.message parameters are provided. The adapter will look for the pi.template.name, pi.template.variant, and other parameters from other sources.

https://pf_host:pf_port/idp/startSSO.ping?PartnerSpId=SP_connection_ID
  &pi.template={
    "variables": {
      "sum": "1,000,000"
    }
  }&pi.clientContext={
    "alert.message": "Confirm your money transfer"
  }

You can use a mix of parameters that contain a single value and parameters that contain JSON objects:

https://pf_host:pf_port/idp/startSSO.ping?PartnerSpId=SP_connection_ID
  &pi.template={
    "name": "transaction",
    "variables": {
      "sum": "1,000,000",
        "recipient": "Charlie Parker"
    }
  }&pi.clientContext={
    "alert.color": "red"
  }
&pi.template.variant=money_transfer
&pi.template.variables.currency=USD
&pi.clientContext.alert.message=Confirm%20your%20money%20transfer