Dynamic parameters support


As part of the integration of the PingID SDK and PingFederate user authentication flow, PingFederate passes parameters to the PingID SDK adapter. The PingID SDK adapter forwards those parameters to the PingID SDK server. There are scenarios where the steps of the authentication flow are determined according to parameters whose values are only determinable at run time. An example is an authentication device used by multiple users, which is used to scan a QR code to initiate the user authentication process. In this case, the PingID SDK server should receive the parameter which determines whether the user list should be presented on the mobile device or on a web browser. Thus, the PingID SDK adapter supports the transfer of dymamic parameter values from PingFederate to the PingID SDK adapter.

The following methods may be used to encapsulate dynamic data:

Both of the above structure declarations are supported by the following methods for passing the dynamic parameter values to the PingID SDK server:

Dynamic parameter attributes

The PingID SDK adapter supports the following attributes. All attributes are optional.

Attribute Description
pingIdSdkAdapterContext Provides context to the PingID SDK Adapter HTML template, to support additional adapter logic.
The pingIdSdkAdapterContext dynamic parameter is converted into the $pingIdSdkAdapterContext velocity parameter within the PingID SDK adapter HTML template.
For example, when processing a particular type of transaction such as a money transfer, the adapter may be directed to display an alternative success screen, or different texts.
The pingIdSdkAdapterContext parameter can be formatted as a JSON object or as an single value. See Adapter context examples.
pingIdSdkClientContext Data that the customer server may transfer to the customer app.
pingIdSdkPushTitle The text of the title of the notification message.
pingIdSdkPushBody The text of the body of the notification message.
pingIdSdkApplicationId The application ID, which may be used in order to override the application ID which is defined in the PingID SDK adapter configuration. This is significant for scenarios where multiple apps are connected to PingFederate.
pingIdSdkSkipSuccessScreens If this parameter is set, it overrides the “Success Screens” PingID SDK adapter configuration value, which determines whether success screens are displayed.
Possible values:
  • true
  • false
pingIdSdkSkipErrorScreens If this parameter is set, it overrides the “Error Screens” PingID SDK adapter configuration value, which determines whether error screens are displayed.
Possible values:
  • true
  • false
pingIdSdkSkipTimeoutScreens If this parameter is set, it overrides the “Timeout Screens” PingID SDK adapter configuration value, which determines whether the timeout screen is displayed.
Possible values:
  • true
  • false

The following attributes are QR code related:

Attribute Description
pingIdSdkUserApprovalRequired Determines whether user approval is required after the user successfully scanned the QR code or clicked on the deep link.
Default: false.
If this value is set to “true”, the PingID SDK Server expects a user input of approval or denial.
pingIdSdkWebUserSelection If the device which successfully scanned the QR code or activated the deep link is paired with more than one user, the user selection is done in the mobile by default. If webUserSelection is true, the PingID SDK Adapter will display the user list in the browser.
pingIdSdkQrCodeClientContext Data that the customer server may transfer to the customer app once the user successfully scanned the QR code.
pingIdSdkQrCodePushTitle The text of the title of the notification message. The notification message is sent only if the web selects the users, and user approval is required.
pingIdSdkQrCodePushBody The text of the body of the notification message. The notification message is sent only if the web selects the users, and user approval is required.

Declare individual attributes

The PingID SDK adapter supports the declaration of individual attributes and the assignment of their values. For example:

{
  "pingIdSdkClientContext": "Are you sure you want to sign-on?",
  "pingIdSdkApplicationId": "123456"
}

Declare a single JSON structure containing required attributes

The PingID SDK adapter supports the declaration of attributes and the assignment of their values within a JSON structure. The dynamic parameters must be declared in the pingIdSdkData attribute. For example, the adapter can set the pingIdSdkClientContext and pingIdSdkPushTitle attributes values in the pingIdSdkData attribute:

pingIdSdkData:
{
  "pingIdSdkClientContext": "Are you sure you want to sign-on?",
  "pingIdSdkApplicationId": "123456"
}

Adapter context examples

The following examples demonstrate logic support, using the pingIdSdkAdapterContext dynamic parameter declared as a single value, or as a JSON object. Both examples display additional logic in the context of a money transfer transaction.

  • pingIdSdkAdapterContext declared as a single value:

    pingIdSdkAdapterContext = "money transfer"

    The pingIdSdkAdapterContext parameter can be used in the PingID SDK adapter HTML template in the following way:

    #if($pingIdSdkAdapterContext == "money transfer")
        <div class="text">$messages.getMessage("pingid.sdk.authenticated.label.money.transferred")</div>
    #else
        <div class="text">$messages.getMessage("pingid.sdk.authenticated.label.authenticated")</div>
    #end
  • pingIdSdkAdapterContext declared as a JSON object:

    pingIdSdkAdapterContext={"transaction": "money transfer"}

    The pingIdSdkAdapterContext parameter can be used in the PingID SDK adapter HTML template in the following way:

    #if($pingIdSdkAdapterContext && $pingIdSdkAdapterContext.transaction == "money transfer")
        <div class="text">$messages.getMessage("pingid.sdk.authenticated.label.money.transferred")</div>
    #else
        <div class="text">$messages.getMessage("pingid.sdk.authenticated.label.authenticated")</div>
    #end

Pass dynamic parameter values from within PingFederate

The PingID SDK adapter can receive the dynamic parameter values from the preceding adapter in the PingFederate policy flow. For example, the HTML Form adapter can pass parameter values to the PingID SDK adapter. The dynamic parameter values can be set within attributes. The attributes may be declared either as individual attributes, or as a JSON structure comprising a single attribute pingIdSdkData which contains the required attributes.

Pass dynamic parameter values from the customer server

The PingID SDK adapter can receive the dynamic parameter values from the customer server, as claims in the request object. Refer to “Passing a Request Object”: https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.6.1.

The dynamic parameter values can be set within attributes. The attributes may be declared either as individual attributes, or as a JSON structure comprising a single attribute pingIdSdkData which contains the required attributes.

Example of claim with individual attributes

The following example presents a request object claim where the pingIdSdkClientContext and pingIdSdkPushTitle attributes are set individually:

{
 "pingIdSdkUserApprovalRequired": true,
 "pingIdSdkClientContext": "Some Data",
 "iss": "s6BhdRkqt3",
 "aud": "https://server.example.com",
 "response_type": "code id_token",
 "client_id": "s6BhdRkqt3",
 "redirect_uri": "https://client.example.org/cb",
 "scope": "openid",
 "state": "af0ifjsldkj",
 "nonce": "n-0S6_WzA2Mj",
 "max_age": 86400,
 "claims":
  {
   "userinfo":
    {
     "given_name": {"essential": true},
     "nickname": null,
     "email": {"essential": true},
     "email_verified": {"essential": true},
     "picture": null
    },
   "id_token":
    {
     "gender": null,
     "birthdate": {"essential": true},
     "acr": {"values": ["urn:mace:incommon:iap:silver"]}
    }
  }
}

Example of claim with JSON structure

The following example presents a request object with a JSON claim containing the dynamic parameter attributes. When using this method, the JSON claim name must be pingIdSdkData.

{
 "iss": "s6BhdRkqt3",
 "aud": "https://server.example.com",
 "response_type": "code id_token",
 "client_id": "s6BhdRkqt3",
 "redirect_uri": "https://client.example.org/cb",
 "scope": "openid",
 "state": "af0ifjsldkj",
 "nonce": "n-0S6_WzA2Mj",
 "max_age": 86400,
 "pingIdSdkData":
  {
   "pingIdSdkUserApprovalRequired": true,
   "pingIdSdkQrCodeClientContext": "Some Data",
   "pingIdSdkQrCodePushTitle": "Some Data",
   "pingIdSdkQrCodePushBody": "Some Data",
   "pingIdSdkClientContext": "Some Data",
   "pingIdSdkPushTitle": "Some Data",
   "pingIdSdkPushBody": "Some Data",
   "pingIdSdkApplicationId": "123456"
  }
 "claims":
  {
   "userinfo":
    {
     "given_name": {"essential": true},
     "nickname": null,
     "email": {"essential": true},
     "email_verified": {"essential": true},
     "picture": null
    },
   "id_token":
    {
     "gender": null,
     "birthdate": {"essential": true},
     "acr": {"values": ["urn:mace:incommon:iap:silver"]}
    }
  }
}

Refer to the entries for Require Signed Request and JSON Web Key Set (JWKS) in the “Configure an OAuth client” topic of the PingFederate documentation:
https://documentation.pingidentity.com/pingfederate/pf/index.shtml#adminGuide/configuringClient.html.

Dynamic parameters in the Moderno sample app

The dynamic parameter feature is supported from PingFederate 8.4 and PingID SDK adapter 1.2.
The Moderno sample app for PingID SDK adapter 1.2 includes a number of settings which support dynamic parameters.

The Moderno sample server code demonstrates passing dynamic PingId SDK parameters to PingFederate.