PingOne for Customers Plus

CIAM Plus With Protect - Device Authentication - Subflow

The CIAM Plus With Protect - Device Authentication - Subflow lets users authenticate using a known device, including options for voice, email, SMS, mobile authenticator app, time-based one-time passcode (TOTP), one-time passcode (OTP), FIDO2, and a magic link using the CIAM Plus With Protect - Magic Link Authentication - Subflow.

Purpose

The CIAM Plus With Protect - Device Authentication - Subflow enables users to authenticate using a known device. The flow evaluates the devices associated with the user account:

  • If no devices are present, it invokes the CIAM Plus With Protect - 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

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 security keys and biometrics are available. The flow then progresses to the Filter and Mask Devices section.

Filter and Mask Devices

Filters the list of available devices to create a list of usable devices, then creates a list of masked devices. 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, then branches based on the MFA status.

If the MFA status is assertion_required, OTP_required, or push_confirmation_required, the flow progresses to the Default Device Enrichment section.

If the MFA status is device_selection_required, function nodes determine whether the user has only one MFA device and whether magic link is enabled. If the user has more than one device, or if the user has one device and magic link is enabled, the flow progresses to the Device Selection section. If the user has only one device and magic link is not enabled, a PingOne node begins MFA with the available device and the flow progresses to the Default Device Enrichment section.

Call Magic Link Authentication

Invokes the CIAM Plus With Protect - 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 CIAM Plus With Protect - Magic Link Authentication - Subflow flow is invoked, and the flow then progresses to the Return Success section or to the beginning of 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. If the user selected Cancel, the flow progresses to the Return Success section.

Default Device Enrichment

Uses a function node to enrich the device details, then the flow progresses to the Handle TOTP, SMS, VOICE, MOBILE and EMAIL OTP Authentication section if an OTP is required, to the Handle FIDO2 Authentication section if assertion is required, and to the Mobile Push Flow section if push confirmation is required.

Handle TOTP, SMS, VOICE, MOBILE and EMAIL OTP Authentication

Uses function nodes to initialize a variable to track the number of OTP attempts and check the device type, then presents the user with an HTML page with options to enter the passcode, change devices, or resend the OTP.

The resend option uses function nodes to increment the number of OTP attempts and verify that the limit has not been reached, then uses a PingOne node to resend the OTP. A message indicating that the OTP has been resent is then displayed to the user.

The change device option progresses the flow to the Device Selection section.

If the user enters a passcode, a function node converts the passcode to lowercase, then a PingOne MFA node evaluates the passcode. If it matches, the flow progresses to the Return Success section. If it fails, an error message is displayed.

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 FIDO2 assertion to authenticate the user. If the authentication succeeds, the flow progresses to the Return Success section. If the authentication fails, an error message is displayed.

Mobile Push Flow

Displays an HTML page that presents users with multiple options.

If the user selects Use Passcode, the flow progresses to the Mobile Passcode Flow section.

If the user selects Different Method, the flow progresses to the Device Selection section.

If the user proceeds using push notification, a PingOne node reads the user’s response, then a function node branches the flow based on the device authentication status.

  • If device authentication completed successfully, a function node saves the authentication method value, then the flow progresses to the Return Success section.

  • If device authentication failed, the flow progresses to either the Mobile App Timed Out section or the Return Error section depending on the reason for the failure.

  • If push confirmation is still required, polling continues.

  • If push confirmation timed out, the flow progresses to the Mobile Passcode Flow section if OTP fallback is allowed.

Mobile Passcode Flow

Displays an HTML page that presents users with multiple options.

If the user selects Retry Authentication, a PingOne node retries the authentication and the flow returns to the beginning of this section.

If the user selects Different Method, the flow progresses to the Device Selection section.

If the user submits an OTP, a PingOne node validates the OTP and a function node saves the authentication method value. The flow then progresses to the Return Success section.

Mobile App timed out

Displays an error message that presents the user with multiple authentication options.

If the user selects Retry Authentication, a PingOne node retries the authentication and the flow progresses to the Mobile Push Flow section.

If the user selects Different Method, the flow progresses to the Device Selection section.

Return Success

Sends a success JSON response, indicating that the flow 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

No

The PingOne user’s email address to use for magic link authentication.

p1UserId

Yes

The user ID of the current user.

magicLinkEnabled

No

A boolean that indicates whether magic link is enabled.

p1MFAPolicyID

No

The ID of the PingOne MFA policy to use in the flow.

allowedDeviceTypes

No

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

otpFallbackAllowed

No

A boolean that indicates whether the user can fall back to a one-time passcode if push confirmation times out.

cancelEnabled

No

A boolean that indicates whether the user can cancel MFA authentication.

resendOtpLimit

Yes

The maximum number of times the user can resend the OTP.

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

subflowResult

The result status of the flow.

authMethod

The authentication method that was configured by the flow.

errorMessage

The error message to display in the parent flow.

errorDetails

The details of the error that occurred in this flow.

Variables and parameters

This flow uses the following variable or parameter values:

Variable name Parameter name Description

resendOtpAttempts

None

The number of times the user has resent the OTP.