Purpose

The OOTB - Device Authentication - Subflow enables users to authenticate using a known device. The flow uses PingOne Protect to check for bots and high-risk accounts, then evaluates the devices associated with the user account:

  • If no devices are present, it invokes the OOTB - Magic Link Authentication - Subflow flow.
  • If more than one device is present, it enables the user to select a device.
  • If only one device is present, or if the user has selected a device, it enables the user to select an authentication method and authenticates the user with the selected method.

Structure

Diagram of the OOTB - Device Authentication - Subflow structure, as described below.

This flow is divided into sections using teleport nodes:

Gather Browser And Devices Data
Uses a PingOne node to gather the user's existing devices. Next, an HTML node evaluates the user's browser to determine if biometrics are available. The flow then progresses to the PingOne Protect Threat Detection Analysis section.
PingOne Protect Threat Detection Analysis

Uses a PingOne node to look up the user, then invokes the OOTB - PingOne Protect Threat Detection - Subflow subflow.

If the OOTB - PingOne Protect Threat Detection - Subflow subflow completes successfully, the PingOne Protect values are saved as variables and a comparison node determines whether the device is a known device. If not, a PingOne node sends an email notification to the user.

A function node then examines the risk score.
  • If the risk score is low, the flow progresses to the Filter and Mask Devices section.
  • If the risk score is medium, a function node examines the number of registered MFA devices. If there are no MFA devices, PingOne nodes create a device and send an email to the user informing them that the device has been created. The flow then progresses to the Filter and Mask Devices section.
  • If the risk score is high, a PingOne node updates PingOne Protect with the failed evaluation and an error message is displayed.

If the OOTB - PingOne Protect Threat Detection - Subflow subflow does not complete successfully, any available PingOne Protect values are saved as variables. PingOne nodes send an email notification to the user informing them that their account is disabled, update the user's status, and update the user's risk notification. An error message is then displayed.

Filter and Mask Devices
Filters the list of available devices to create a list of usable devices, then masks the device information so that the devices can be identified without displaying the full device information. The flow then progresses to the Check If MFA Enabled And Any Device Active section.
Check If MFA Enabled And Any Device Active
Uses a PingOne node to check the user's MFA status. If MFA is enabled and the user has active devices, the flow progresses to the Decide Authentication Path Based On MFA Policy section. If MFA is not enabled or the user has no active devices, the flow progresses to the Call Magic Link Authentication section.
Decide Authentication Path Based On MFA Policy
Uses a PingOne node to begin MFA authentication. If an assertion or an OTP is required, the flow progresses to the Default Device Enrichment section. If the user has multiple devices, or if the user has only one usable device and magic link is enabled, the flow progresses to the Device Selection section. If the user has one usable device and magic link is not enabled, the flow progresses to the Default Device Enrichment section.
Call Magic Link Authentication
Invokes the OOTB - Magic Link Authentication - Subflow flow if magic link authentication is enabled. The flow then progresses to the Return Success section.
Device Selection
Presents the user with an HTML page on which they can select a device. If the user selected magic link, the OOTB - Magic Link Authentication - Subflow flow is invoked, and the flow then progresses to the Return Success section or to the Device Selection section depending on the subflow results. If the user selected another authentication method, a PingOne records their selection and the flow progresses to the Default Device Enrichment section.
Default Device Enrichment
Uses a function node to enrich the device details, then the flow progresses to the Handle SMS and Email OTP Authentication section if an OTP is required or to the Handle FIDO2 Authentication section if assertion is required.
Handle SMS and Email OTP Authentication
Performs authentication using a one-time passcode. The section sends an OTP to the user, and presents the user with an HTML page with options to enter the passcode, change devices, or resend the OTP. The resend option uses a PingOne node to resend the OTP. The change device option progresses the flow to the Device Selection section. If the user enters a passcode, a PingOne MFA node evaluates the passcode. If it matches, the flow progresses to the Return Success section. If it fails, the flow progresses to the Return Error section.
Handle FIDO2 Authentication
Performs authentication using a security key or biometrics. It presents users with the option to select a different device or continue with the current device. If the user selects a different device, it progresses to the Device Selection section. If the user continues, it uses a PingOne MFA node with FIDO assertion to authenticate the user. If the authentication succeeds, the flow progresses to the Return Success section. If the authentication fails, the flow progresses to the Return Error section.
Return Success
Sends a success JSON response, indicating that the flow has completed successfully.
Return Error
Sends an error JSON response, indicating that the flow completed unsuccessfully.

Input schema

This flow has the following inputs:

Input name Required Description

email

Yes

The email address to use for registration.

pingOneUserId

Yes

The user ID of the current user.

ciam_magicLinkEnabled

Yes

A boolean that indicates whether magic link is enabled.

allowedDeviceTypes

Yes

A string containing any or all of SMS, EMAIL, FIDO2 indicating the allowed device types.

ciam_companyLogo

No

The company logo.

Used only when the main flow was launched using the widget.

Output schema

This flow has the following outputs:

Output name Description

ciam_pingOneUserId

The user ID of the current user.

ciam_subflowResult

The result status of the flow.

ciam_authMethod

The authentication method that was configured by the flow.

ciam_errorMessage

The error message to display in the parent flow.

Variables and parameters

This flow uses the following variable or parameter values:

Variable name Parameter name Description

ciam_magicLinkEnabled

isEmailMagicLinkEnabled

Indicates whether magic links are enabled in your environment.

ciam_logoStyle

None

The HTML style to use for your company logo.

ciam_logoUrl

None

The URL for your company logo.

ciam_companyName

None

Displays the name of your company.

ciam_protectPredictor

None

The recommendation made by PingOne Protect.

ciam_protectDeviceStatus

None

The status of the user's device as determined by PingOne Protect.

ciam_protectRiskID

None

The risk ID of the current user as used by PingOne Protect.

ciam_protectRiskLevel

None

The risk level of the current user as determined by PingOne Protect.