Connectors

Challenge Connector

The Challenge connector allows you to branch your PingOne DaVinci flow to handle an external event, such as a multi-factor authentication (MFA) step.

By using the Challenge connector, you can show the user a message and “waiting” indicator in the main flow while a secondary flow interacts with the user elsewhere. When the secondary flow is done, the Challenge connector can trigger the main flow to continue.

The connector works by creating, updating, or checking the status of a “challenge” in your flow. Challenges are special variables that can be created by several connectors, including the Challenge connector, Flow Conductor and some authentication and verification connectors.

Other connectors, such as the HTTP connector, can pause the flow until the status of a challenge changes.

The Challenge connector updates the status of a challenge, which triggers the waiting HTTP connector to continue the flow.

A screen capture that shows an overview of how the Challenge connector branches a flow.

Setup

Setting up the Challenge connector

In DaVinci, add a Challenge connection. For help, see Adding a connector.

This connector doesn’t have a configuration at the environment level. You configure it in your flow instead.

Using the connector in a flow

The Challenge connector supports a variety of use cases, such as:

Building an MFA sign-on flow

In this example, we want our user to complete an MFA challenge after entering their username and password. We’ll show an HTML message in the browser telling the user to complete MFA. At the same time, we’ll start the MFA connector in a secondary flow, which pushes a notification to the user’s phone. When the user completes MFA on their phone, our secondary flow triggers the HTML message to continue the main flow.

Before you start, you’ll need:

  • A sign-on form. You can create one with the HTTP connector.

  • An MFA connector, such as the PingOne MFA connector.

    1. Create the challenge:

      1. In your flow, following the sign-on form, add the Challenge connector and select the Add Transaction Status capability. Select the new node in your flow.

      2. Turn off Is challenge record complete.

      3. In the Challenge Status list, select started.

    2. Show a page with a “waiting” animation until the user clicks the link:

      1. Following your Add Transaction Status node, add an HTTP connector and select the Custom HTML Message capability. Select the new node in your flow.

      2. Build your message in the HTML Template field. To show a “waiting” animation on the page, click {} and select the skpolling variable from SK-Component.

        A screen capture that shows the user inserting the skpolling variable into the Message field.

      3. In the Challenge field, click {} and select the challenge variable from your Add Transaction Status node. Turn on Enable Polling.

        This pauses the main flow on this page until the challenge status changes. We’ll update the challenge status in the secondary flow.

        Any change in the challenge status, regardless of the value, will cause this flow to continue.

    3. Build a secondary flow that sends the MFA push and updates the challenge status:

      1. Following your Add Transaction Status node, parallel to your Custom HTML Template node, add an MFA node. In our example, we use the PingOne MFA connector. You can use your MFA service of choice or link to a subflow using the Flow conductor connector.

      2. Configure your MFA node by following its documentation. If you are using the PingOne MFA connector, see PingOne MFA.

      3. Following your MFA node, add a Challenge connector and select the Update Transaction Status capability.

      4. In the Challenge field, click {} and select the challenge variable from your Add Transaction Status node.

      5. Turn on Is challenge record complete. This indicates to DaVinci that our Custom HTML Template can stop polling for the status of this challenge.

      6. In the Challenge Status list, select approved.

    4. Following your Custom HTML Template “waiting” page in the main flow, continue building the rest of your flow. For example, you could direct the user to their user account self-service portal.

Capabilities

Add Transaction Status

Add the transaction status challenge to the flow.

Show details

  • Properties

  • Input Schema

  • Output Schema

isChallengeComplete toggleSwitch
challengeStatus dropdownWithCreate

started:

This status signifies that the challenge has been created and can be polled until the status changes or times out

approved:

This status signifies that the challenge has been approved and should be treated as a success event

denied:

This status signifies that the challenge has been denied. This status will still be treated as a success event and the flow is expected to move forward to the true path. Flow can then decide what next to do with the denied status

Challenge Timeout in seconds (default 300secs) textField
updatedByFlowId textField
claimsNameValuePairs selectNameValueListColumn

  • default object

    • parameters object

      • challengeStatus string

      • updatedByFlowId string

  • output object

    • challenge string

    • challengeStatus string

    • updateByFlowId string

Output Example

 { "challenge" : "IXaa0MwwUFtrI4AJedpr4ha40wZmEeOisisRPFlnA0c",
  "challengeStatus" : "started",
  "updateByFlowId" : "MwwUFtrI4AJedpr4ha40wZmEeO" }

Update Transaction Status

Update the transaction status challenge in the flow.

Show details

  • Properties

  • Input Schema

  • Output Schema

Challenge textField
isChallengeComplete toggleSwitch
challengeStatus dropdownWithCreate

started:

This status signifies that the challenge has been created and can be polled until the status changes or times out

approved:

This status signifies that the challenge has been approved and should be treated as a success event

denied:

This status signifies that the challenge has been denied. This status will still be treated as a success event and the flow is expected to move forward to the true path. Flow can then decide what next to do with the denied status

updatedByFlowId textField
claimsNameValuePairs selectNameValueListColumn

  • default object

    • parameters object

      • challenge string minLength: 1 maxLength: 100

        Unique string to identify the Transaction

      • challengeStatus string minLength: 1 maxLength: 50

      Current status of the Transaction

      • updatedByFlowId string minLength: 1 maxLength: 100

    Id of the flow updating the challenge

  • output object

    • challenge string

    • challengeStatus string

    • updateByFlowId string

Output Example

 { "challenge" : "IXaa0MwwUFtrI4AJedpr4ha40wZmEeOisisRPFlnA0c",
  "challengeStatus" : "approved",
  "updateByFlowId" : "MwwUFtrI4AJedpr4ha40wZmEeO" }

Get Transaction Status

Retrieve transaction status information in the flow.

Show details

  • Properties

  • Input Schema

  • Output Schema

Challenge textField

  • default object

    • parameters object

      • challenge string minLength: 1 maxLength: 100

    Unique string to identify the Transaction

  • output object

    • challenge string

    • challengeStatus string

    • updateByFlowId string

Output Example

 { "challenge" : "IXaa0MwwUFtrI4AJedpr4ha40wZmEeOisisRPFlnA0c",
  "challengeStatus" : "approved",
  "updateByFlowId" : "MwwUFtrI4AJedpr4ha40wZmEeO",
  "createdDate" : 1.6353453453E10,
  "statusUpdatedDate" : 1.6353453453E10 }

Poll for Transaction Status

Poll for transaction status information in the flow.

Show details

  • Properties

  • Input Schema

  • Output Schema

Challenge textField
pollInterval textField
pollRetries textField

  • default object

    • parameters object

      • challenge string minLength: 1 maxLength: 100

        Unique string to identify the Transaction

      • pollInterval number

      Poll Interval in ms

      • pollRetries number

    Number of Poll Retries

  • output object

    • challenge string

    • challengeStatus string

    • updateByFlowId string

Output Example

 { "challenge" : "IXaa0MwwUFtrI4AJedpr4ha40wZmEeOisisRPFlnA0c",
  "challengeStatus" : "approved",
  "updateByFlowId" : "MwwUFtrI4AJedpr4ha40wZmEeO" }