Comparison of FOS vs. Direct MFA API flows

In PingOne MFA Integration Kit version 4.0, the PingOne MFA IdP Adapter migrates from integrating with PingOne via the authentication policy in the Flow Orchestration Service (FOS), used in previous versions, to direct MFA Device Authentication APIs.

Flow changes

This table compares the legacy FOS-based orchestration used in earlier versions with the direct API architecture introduced in version 4.0.

Capability Deprecated FOS-Based Flow New Direct MFA API Flow

Capability	Deprecated FOS-Based Flow	New Direct MFA API Flow
Orchestration	Managed by FOS via `/as/authorize`.	Managed directly by the MFA Adapter.
API Endpoint	Invokes OIDC-based Flow APIs.	Invokes `/deviceAuthentications` service APIs.
State Management	Handled internally by FOS.	Managed by the MFA Adapter across API calls.
Token Handling	Returns OIDC tokens (`access_token`, `id_token`).	Returns specific attributes (device ID, enrollment status) directly.
Session Context	Relies on PingOne OIDC session tracking.	Uses PingFederate as the source of truth for session information.

Orchestration

Managed by FOS via /as/authorize.

Managed directly by the MFA Adapter.

API Endpoint

Invokes OIDC-based Flow APIs.

Invokes /deviceAuthentications service APIs.

State Management

Handled internally by FOS.

Managed by the MFA Adapter across API calls.

Token Handling

Returns OIDC tokens (access_token, id_token).

Returns specific attributes (device ID, enrollment status) directly.

Session Context

Relies on PingOne OIDC session tracking.

Uses PingFederate as the source of truth for session information.

Setup and migration from version 3.2

Upgrading to version 4.0 requires moving decision logic from the authentication policy (FOS) into the PingFederate environment.

Core contract and attribute changes

The id_token and access_token core contracts have been removed. If existing policy rules reference these attributes, they must be updated.

For the p1.enrollment attribute source, do one of the following:

Update the expression value to pingone.mfa.enrollment.

Or
Remove the p1.enrollment attribute entirely and use the core contract attribute pingone.mfa.enrollment, ensuring it is mapped in all relevant locations.

MFA Policy for Authentication

The MFA Policy for Authentication field replaces the PingOne Authentication Policy text field. If you are upgrading from version 3.2, you must manually select the appropriate MFA policy from this list.

User Not Found Failure Mode

This setting now exclusively covers users who do not exist in the directory. It no longer applies to disabled users or those with the MFA service disabled.

For those cases, use the new settings available in the MFA Policy under User Access Configuration:

Block authentication when user status is disabled
Block authentication when user’s MFA is disabled

When Block authentication when user’s MFA is disabled is enabled, blocked authentication attempts now return com.pingidentity.pingone.mfa_bypassed_user_mfa_disabled instead of com.pingidentity.pingone.mfa_bypassed_invalid_user, providing more accurate status reporting.

One-Time Device Display Mode

The default display mode is now Standalone. If your previous adapter instance had One-Time Device Display Mode enabled, you must manually select With Paired Devices.

User-Agent header format

The User-Agent header format has changed from PingFederate to PingFederate/{version} PingOne-MFA-Integration-Kit/{version}.

Migrating configuration from the PingOne Authentication Policy

Risk and Protect conditions: Conditions such as IP reputation, geo-velocity, and anonymous network detection are no longer handled by the MFA Adapter. You must now configure these in the PingFederate Authentication Policy using the PingOne MFA Protect Integration Kit.
NONE OR INCOMPATIBLE METHODS: If configured, migrate this to the No Device Failure Mode field in the MFA Adapter.

Change in behavior: No Device Failure Mode covers only users with zero registered devices. Users with incompatible devices are treated as BLOCKED.
Last Sign-on Older Than: If configured, migrate this to PingFederate native session management. The MFA Adapter does not handle sessions.
Accessing from an Out-of-Range IP Address: If configured, migrate this to the MFA for Accessing from IP out of range field in the MFA Adapter.
Being a Member of Any of These Populations: If configured, migrate this to the MFA by User Population field in the MFA Adapter.
User Attributes: If configured, migrate this to the MFA for User Attributes table in the MFA Adapter.

Adapter configuration changelog

The architectural shift to direct APIs results in several changes to the adapter’s configuration UI.

Added or updated fields

Field	Description
MFA Policy for Authentication	Replaces the legacy Authentication Policy text field with a dynamic list.
No Device Failure Mode	New setting to Block or Bypass authentication when no usable MFA methods exist.
MFA by User Population	New text field to trigger MFA based on PingOne MFA population membership.
MFA for Accessing from IP out of range	New field for CIDR-based MFA enforcement within the adapter.
MFA for User Attributes	A new table-based configuration to trigger MFA based on specific user attribute values.

Field

Description

MFA Policy for Authentication

Replaces the legacy Authentication Policy text field with a dynamic list.

No Device Failure Mode

New setting to Block or Bypass authentication when no usable MFA methods exist.

MFA by User Population

New text field to trigger MFA based on PingOne MFA population membership.

MFA for Accessing from IP out of range

New field for CIDR-based MFA enforcement within the adapter.

MFA for User Attributes

A new table-based configuration to trigger MFA based on specific user attribute values.

Removed or changed fields

JWKS Cache Duration: Removed. Direct API calls eliminate the need for JWKS endpoint polling.
User Not Found Failure Mode: Changed behavior. This now only applies when a user does not exist in the directory; it no longer covers disabled users or disabled MFA service states.
CIBA Authenticator: The change to the MFA Policy for Authentication list also applies to all CIBA authenticator configurations.

Authentication initiation

In earlier versions, the MFA Adapter initiated authentication using the OAuth Authorization API (/as/authorize), which triggered FOS to coordinate multiple PingOne MFA calls.

In version 4.0, OAuth authorization is decoupled from MFA execution. The MFA Adapter invokes the PingOne MFA Device Authentication APIs directly as a discrete step within the PingFederate authentication policy.

Attribute and claim mapping

With the removal of FOS, the adapter no longer receives or returns synthetic OIDC tokens. Instead, the adapter receives raw metadata from the MFA service and injects it into the PingFederate attribute map.

Removed tokens

To simplify security semantics and avoid unnecessary key management, the following attributes are no longer returned in the authnAdapterResponse.attributeMap:

access_token
id_token

If existing PingFederate policy rules or OGNL expressions rely on id_token, they must be updated to use the new core contract attributes below.

New core contract attributes

The required claims for downstream applications are now returned directly as adapter attributes:

pingone.mfa.device.id
pingone.mfa.enrollment

Parameter mapping

The transition to direct APIs changes how specific parameters are passed from PingFederate to PingOne MFA.

MFA Policy: Parameters previously passed as acr_values are now mapped to policy.id.

Learn more about specific field configurations in PingOne MFA IdP Adapter settings reference.