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:

• Declare individual attributes
• Declare a single JSON structure containing required attributes

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

• Pass dynamic parameter values from within PingFederate
• Pass dynamic parameter values in the authorization request

Dynamic parameter attributes

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

The following attributes are QR code related:

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 in the authorization request

The PingID SDK adapter can receive the dynamic parameter values from the authorization request, 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.

• Refer to the code example in the PingFederateRequestGenerator class for creating and signing dynamic data.
• Refer to Know the PingID SDK using the Moderno sample app for further information on getting started with Moderno.