(Workforce only) Transitioning from the PingID Adapter to the PingOne MFA IdP Adapter
If you currently use the PingID Adapter for PingFederate integration, you can now use the PingOne MFA Integration Kit to integrate directly from PingOne without requiring the legacy PingID admin portal. This topic covers requirements, differences in field names and attributes, and features not yet available in the PingOne MFA Integration Kit.
|
The PingOne MFA Integration Kit and the PingID Adapter are not interchangeable versions of the same product.
|
There are a few key differences to be aware of before you start:
- Configuration
-
-
PingOne MFA IdP Adapter: Configuration is split between PingOne admin portal and the adapter.
-
PingID Adapter: Configuration is split between the PingID admin portal and the adapter itself.
-
- Authenticator flow UI
-
-
PingOne MFA IdP Adapter: Includes Native UI HTML files, which are bundled with the adapter.
-
PingID Adapter: No native UI
-
- Device Management
-
-
PingOne MFA IdP Adapter: Device management can be handled natively in the adapter, without requiring device management through an external application.
-
PingID Adapter: Device management requires an external application (such as the PingID admin portal Devices page, or the PingOne MyAccounts page).
-
- Download manifest
-
The PingOne MFA Integration Kit has a different download manifest from the PingID Adapter. Before deploying, review the PingOne MFA Integration Kit download manifest to make sure you have the correct files.
Requirements
| Requirement | Details |
|---|---|
PingFederate |
11.3 or later |
PingOne MFA Integration Kit |
4.1 or later |
Java |
17 or later |
PingOne environment |
Singapore and Canada geographies: requires a PingOne for Workforce environment. All other geographies: requires a PingOne environment with the PingID service. |
|
Passwordless authentication using the PingID Desktop App (including Conditional UI) requires PingFederate 13.x or later. |
Migrating your configuration
Create a new PingOne MFA IdP Adapter instance and use it to recreate your configuration manually. Test the configuration and when you are done, transition your users to use the new PingOne MFA IdP Adapter instance.
-
Update the PingOne MFA Integration Kit and deploy it to your PingFederate instance.
-
Configure a new PingOne MFA IdP Adapter instance, referring to Changed fields for field names that changed.
-
Update your PingFederate authentication policies to use the new adapter instance.
-
If your authentication policies use PingID Adapter output attributes in downstream policy steps, update them to use the equivalent PingOne MFA Integration Kit attributes. See Changed attributes.
|
Changed fields
The following PingID Adapter fields have new names or different behavior in the PingOne MFA IdP Adapter.
| PingID Adapter field | PingOne MFA IdP Adapter field | Notes |
|---|---|---|
Authentication During Errors |
Service Unavailable Failure Mode |
Expanded to include offline MFA options: Passive offline authentication and Enforce offline authentication. Learn more in (Workforce only) Configuring offline MFA. |
Users Without a Paired Device |
No Devices Failure Mode |
Updated to account for offline MFA scenarios. |
Allow only predefined values for phone or email devices |
Email Field Behavior, SMS Field Behavior, Voice Field Behavior, WhatsApp Field Behavior |
Replaced by per-method field behavior settings. Each field accepts None (blank), Pre-populate (editable), or Pre-populate and Restrict (read-only from the user directory). Learn more in PingOne MFA IdP Adapter settings reference. |
Require PingID Registration |
Prompt Users to Set Up MFA |
Controls whether users without a paired device are prompted to register an authentication method during sign-on. |
LDAP Username Mapping |
Use Username Attribute During Authentication |
Renamed in the PingOne MFA IdP Adapter. Controls whether the value from Username Attribute is used during authentication as well as provisioning. Learn more in PingOne MFA IdP Adapter settings reference. |
Enforce authentication after device registration |
Enforce authentication after device registration |
The field name is unchanged. In the PingOne MFA IdP Adapter, configure this setting in the adapter’s Advanced fields instead of in the PingID admin portal. Learn more in PingOne MFA IdP Adapter settings reference. |
HTML Template |
HTML Template Prefix |
The PingOne MFA IdP Adapter uses a prefix to resolve HTML template files. Specify the prefix that matches your custom templates, or leave blank to use the bundled default templates. |
PingID Heartbeat Timeout |
API Request Timeout |
Controls the timeout for requests to the PingOne MFA API. |
PingID Properties File Name |
N/A |
The PingID Adapter required a PingID-specific properties file. The PingOne MFA IdP Adapter does not use a separate properties file; all configuration is in the adapter itself. |
Keep cookies at sign-off |
Requires the Remember Me adapter |
SLO is supported when the Remember Me adapter is configured in your PingFederate authentication policy. Learn more in Remembered devices setup. |
Refresh UserId Cookie, Cookie Duration |
N/A |
The PingID Adapter managed its own cookie lifecycle. Cookie sign-off and refresh behavior is handled by PingFederate session management, not the PingOne MFA IdP Adapter. |
Changed behavior
The following PingID Adapter behaviors work differently in the PingOne MFA IdP Adapter.
- Just-in-time (JIT) registration
-
-
PingOne MFA IdP Adapter: The PingOne MFA IdP Adapter also provisions missing authentication methods for existing PingOne users, as well as new users with no devices. If a user exists in PingOne but is missing one or more authentication methods, the adapter provisions a device on initial sign-on. Learn more in Enabling user and authentication method provisioning.
-
PingID Adapter: JIT only runs if the user has no devices.
-
- Protect risk evaluation
-
-
PingOne MFA IdP Adapter: Protect risk evaluation is handled by the PingOne Protect Integration Kit that’s chained before the MFA adapter in the PingFederate authentication policy. The MFA adapter receives and acts on the Protect results.
-
PingID Adapter: Risk evaluation was configured directly in the adapter through the Risk Level and PingOne Protect API Response Mapping fields.
-
Changed attributes
The PingID Adapter wrote authentication results to the pingid.authentication.type output attribute. The PingOne MFA Integration Kit uses pingone.mfa.status, which has a different set of values.
If your authentication policies use pingid.authentication.type for branching decisions, update them to reference pingone.mfa.status instead. The pingone.mfa.status values distinguish between web and mobile sign-on contexts. Learn more in PingOne MFA attributes reference.
| PingID Adapter attribute | PingOne MFA IdP Adapter attribute | Notes |
|---|---|---|
|
|
Values differ. See PingOne MFA attributes reference for the full list of |
Authentication domain changes
The following differences exist between the PingOne MFA Integration Kit and the PingID Adapter:
-
PingID Adapter: Redirected users to the PingOne regional domain (pingone.<geography_name>) to complete authentication.
-
PingOne MFA IdP Adapter: Users sign on entirely on your custom domain. The adapter does not redirect users to a PingOne domain during authentication.
If your users authenticate with passkeys or FIDO devices, when transitioning to the PingOne MFA Integration Kit, you’ll need to update the relevant FIDO policy to use a compatible domain (preferably the PingFederate root domain) as the
rpid.
Unsupported Features
The following features are not currently supported in the PingOne MFA Integration Kit:
-
PingID-compatible post-authentication attributes
-
Mandatory enrollment date
-
Passkeys registered with the PingOne domain can’t be used for authentication. The users should use the PingOne MFA Integration Kit device management to re-register their Passkey device. In a future release, the option to re-register a Passkey to a compatible domain will be included as part of the authentication flow.