Configuring transaction approval - PingOne - PingOne Cloud Platform

PingOne
bundle
pingone
ft:publication_title
PingOne
Product_Version_ce
PingOne
PingOne Cloud Platform
category
Administratorguide
ContentType
Guide
Product
Productdocumentation
p1
p1cloudplatform
ContentType_ce
Guide
Product documentation
Guide > Administrator Guide

Transaction approval refers to applications that have operations of differing sensitivity that should trigger additional multi-factor authentication (MFA) events.

For example, a financial application might not require additional user verification for viewing data, but a money transfer above a certain value should trigger the additional MFA event.

You can configure transaction approval for scenarios where strong authentication is required for elevated security for a high-value transaction or for a high-risk resource or service.

Configuring transaction approval using the admin console

You can customize the notification texts for transaction approval, similar to same way in which you customized authentication email notifications.

  1. Configure the transaction notification template with the desired text and optionally some (dynamic) variables.
  2. Invoke an OpenID Connect (OIDC) request with a request parameter that contains the template name and the values for the template variables:
    • For cases where the transaction is approved by a mobile application with the embedded mobile SDK, the request parameter can further contain a context object that can be consumed by the mobile application.
    • For cases where multiple sign-on policies are defined for an application, specify the policy name in the acr_values parameter to invoke a specific policy.
    Note:

    A transaction can be approved by SMS, voice, email, time-based one-time password (TOTP) authenticator app, or mobile push notification. You can create a sign-on policy for limiting the device types that can approve a transaction and specify that policy using the acr_values parameter.

    This is also the step where you can customize notification texts for transaction approval.

  3. Go to User Experience > Notification Templates.
  4. Locate the Transaction template, click the Options menu, and then click Edit.
  5. Edit the relevant delivery method's transaction approval texts, using required and optional dynamic variables.
    Tip:

    For more information and additional configuration options, see Notification templates.

  6. Click Save.

MFA using a mobile application

Configuring transaction approval using the API

Application developers can use the API operations to configure transaction approval. Customizing notification text for transaction approval is similar to customizing notifications and uses an access token generated through the worker app.

  • Use the following POST operation: 
    POST https://api.pingone.com/v1/environments/{{envId}}/templates/{{templateName}}/contents/{{contentId}}
    Note:

    This example uses a push notification. For more information, see Configuring Notifications Template

    PUT https://api.pingone.com/v1/environments/{{envId}}/templates/{{templateName}}/contents/{{contentId}}
{
    "locale":"en",
    "title":"Approve this transfer",
    "body":"Please approve this transfer of ${sum}${currency} to ${recipient}",
    "deliveryMethod":"Push"
}
  • Create a request parameter: 
    "jwtHeader": {
  "alg": "HS256",
  "typ": "JWT"
},
"jwtBody":
{
  "aud": "https://auth.pingone.com/{{envId}}/as",
  "iss": "{{appId}}",
  "pi.template": {
    "name": "transaction",
    "variables": {
      "sum": "1,000,000",
      "currency": "USD",
      "recipient": "Charlie Parker"
    }
  },
  "pi.clientContext": {
    "alert.color": "red"
  }
}
    • pi.template.name must have the value transaction.
    • pi.template.variables must contain the values of the transaction template variables.
    • pi.clientContext is a dictionary of arbitrary values that a mobile app can use to provide context, for example, rendering an alert.
    1. Sign the request using either:
      • The web app's Client Secret, which you can find on the app's Configuration tab.
      • The Allow unsigned JWT requests check box, which you can find on the app's Configuration tab, in the Advanced Configuration section.
  • To invoke an OIDC request, use either browser mode or API mode.

    This example uses both the login_hint_token and request parameters:

    https://auth.pingone.com/{{envId}}/as/authorize?scope=profile&client_id={{webAppId}}&redirect_uri=https://www.example.com&response_type=code&login_hint_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkOTA4ODQ3ZC01MzI5LTQxZWEtODAzZi1kN2IyZTBlOTczMTYiLCJzdWIiOiJmNTg0NDFmYy1iZGY3LTRiYjYtODA1OC1iYTkyOGEzM2NhYjEiLCJhdWQiOiJodHRwczovL2F1dGgucGluZ29uZS5jb20vODlmYmNjZjMtMjJlNS00NjhkLTk4OWYtMDI0NzRlMDViNzcxL2FzIn0.c3tJN0pp6yx2xNopozCN83WSEG-h70cJqcYlom63ZQg&response_mode=pi.flow&acr_values=MFA-Only&request=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2F1dGgucGluZ29uZS5jb20vODlmYmNjZjMtMjJlNS00NjhkLTk4OWYtMDI0NzRlMDViNzcxL2FzIiwiaXNzIjoiZDkwODg0N2QtNTMyOS00MWVhLTgwM2YtZDdiMmUwZTk3MzE2IiwicGkudGVtcGxhdGUiOnsibmFtZSI6InRyYW5zYWN0aW9uIiwidmFyaWFibGVzIjp7InN1bSI6IjEsMDAwLDAwMCIsImN1cnJlbmN5IjoiJCIsInJlY2lwaWVudCI6IkNoYXJsaWUgUGFya2VyIn19LCJwaS5jbGllbnRDb250ZXh0Ijp7ImFsZXJ0LmNvbG9yIjoicmVkIn19.5VQ5aSlvuKws7KMuEwMdseFjL-k2s0thBiNFY2LFkDQ
    • login_hint_token is used for passing a user ID in a passwordless flow.
    • request is used to pass the contextual parameters for the transaction.

MFA using a mobile application