Transaction approval setup - PingFederate - PingOne MFA - PingOne - PingOne Services - PingOne Cloud Platform

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.

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.

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

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

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.

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.

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

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:

{
  "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.

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