One-Time Passcode Integration Kit

Language property and template keys

The Language Property and Template Keys that you define in the One-Time Passcode IdP Adapter instance configuration affect the messages and prompts shown to end users.

The adapter uses these keys in different ways depending on how the adapter is accessed and which notification publisher it interacts with.

Using the PingFederate authentication API

When the PingFederate authentication API provides your web application with a list of notification delivery methods, it includes the Language Property and Template Keys value as the device type.

By having your web application read the device type, you can set different the icons or formatting for each delivery method.

In the example below, the authentication API is prompting the web application to select a delivery method. The methods are defined with these three keys: VOICE, SMS, and EMAIL.

The Notification Delivery Methods table 
{
  "id": "G1j8b",
  "pluginTypeId": "7r5wldvoQS8iEJEpdMYqmA",
  "status": "DEVICE_SELECTION_REQUIRED",
  "devices": [
    {
      "id": "7337a6ac-98b2-4c02-9afd-82aa9f6b55c7",
      "type": "VOICE",
      "target": "+15555"
    },
    {
      "id": "2ac3e6a8-5b3e-4247-b7d8-4d12cec8b9da",
      "type": "SMS",
      "target": "+15555"
    },
    {
      "id": "b6cbaeff-bea2-4cfd-a0fd-3ffe6907df39",
      "type": "EMAIL",
      "target": "an**@example.com"
    }
  ],
  "user": {
    "username": "anonymous"
  },
  "_links": {
    "cancelAuthentication": {
      "href": "https://pf-host:9031/pf-ws/authn/flows/G1j8b"
    },
    "selectDevice": {
      "href": "https://pf-host:9031/pf-ws/authn/flows/G1j8b"
    },
    "self": {
      "href": "https://pf-host:9031/pf-ws/authn/flows/G1j8b"
    }
  }
}

User interface

The template files included in the integration kit show information about your OTP delivery methods. To do this, they use lines from the pingfederate-otp-adapter-messages.properties file that begin with the Language Properties and Templates Key that you define for each delivery method.

For example, you configure a delivery method with a Language Properties and Templates Key value of sms . When asking the user to enter a passcode for that delivery method, the adapter use the following lines to generate the page:

sms.otp.adapter.otp.required.template.header=SMS Authentication
sms.otp.adapter.otp.required.template.message=Enter the passcode you received to continue.
sms.otp.adapter.otp.required.template.otp.sent.text=SMS sent to:
sms.otp.adapter.otp.required.template.resend.button.title=Resend

By default, the pingfederate-otp-adapter-messages.properties file has messages defined for the following keys:

  • email

  • sms

  • voice

You modify the existing messages, or add your own using a new prefix.

SMTP Notification Publisher

When using the SMTP Notification Publisher, the key determines the template file that forms the body of the email message.

For example, if you enter pingfederate.smtp in the Language Properties and Templates Key field, the adapter will use the <pf_install>/pingfederate/server/default/conf/template/mail-notifications/pingfederate.smtp.otp.adapter.template.html file as the body of the email message.

If you are also using the user interface, the adapter will check the pingfederate-otp-adapter-messages.properties file for message lines that begin with pingfederate.smtp. Modify the file accordingly.

Twilio Programmable API Notification Publisher

When using the Twilio Programmable API Notification Publisher, the key determines the template file that forms the body of the notification SMS or voice call.

For example, if you enter twilio.sms in the Language Properties and Templates Key field, the adapter will use the <pf_install>/pingfederate/server/default/conf/template/twilio.sms.otp.adapter.template.html file as the body of the SMS message.

If you are also using the user interface, the adapter will check the pingfederate-otp-adapter-messages.properties file for message lines that begin with twilio.sms. Modify the file accordingly.