PingOne MFA IdP Adapter settings reference

Field descriptions for the PingOne MFA IdP Adapter configuration page.

Standard fields

Field Description

PingOne Environment

Select the PingOne connection that you created in Connecting PingFederate to PingOne.

This field is blank by default.

PingOne Population

If a user does not already exist in PingOne, the adapter provisions the user to this PingOne population.

Applies only when Provision Users is selected.

This list is populated after you select the PingOne Environment.

This field is blank by default.

Application

The PingOne application that you created in Creating a web or native OIDC application in PingOne.

This list is populated after you select the PingOne Environment and PingOne Population.

This field is blank by default.

PingOne Authentication Policy

The policy name that you chose in Creating an MFA authentication policy in PingOne. This overrides any policy named in the requested authentication context.

You can enter multiple policy names by separating them with a space. For example, employees contractors. These must all be "MFA-only" policies, as described in Creating an MFA authentication policy in PingOne.

The adapter maps this value to the acr_values parameter of the PingOne OIDC request.

When this field is blank, the adapter does the following:

Looks for the presence of the pingone-mfa-acr attribute in chained attributes followed by signed request claims object followed by tracked parameters, and if found uses the corresponding as received.
If the pingone-mfa-acr attribute is not provided in any of the above mentioned dynamic parameters, the adapter will attempt to use the value of the RequestedAuthnCtx parameter (for SAML SSO flows) or the acr_values parameter (for OAuth flows) in the request.

This field is blank by default.

MFA policy for registration

Select the PingOne MFA policy that you want to use for device pairing.

Your registration policy can use an MFA policy with different requirements than the MFA policy or policies that the PingOne Authentication Policy uses, so make sure to set up MFA policies that are compatible with each other.

For example, if you use an MFA policy for authentication that requires offline devices and an MFA policy for registration that requires FIDO-compliant mobile devices, you wouldn’t be able to pair any of the device types required for authentication through your registration policy.

If this were the case, you could still set up the device types that you require for authentication through device provisioning. However, you would not be able to use any of your paired devices for authentication.

Advanced fields

Field Description

Test Username

The PingOne username that the adapter uses to test the PingOne MFA connection on the Actions tab.

Enter the username for a user that has a paired device and MFA enabled in PingOne.

This field is blank by default.

Notification Template Variant Override

Overrides the notification template variant that the adapter sends to PingOne for authentication and transaction approval flows. The adapter ignores any pi.template.variant attribute in the PingFederate authentication policy and uses this value instead.

Enter the name of the template variant. For example, if you have a PingOne "transaction" template variant called "money-transfer", enter money-transfer.

This field is blank by default.

HTML Template Prefix

Identifies the set of HTML templates that the adapter uses to show the authentication status or request a one-time password.

If you customize the template file names in the /server/default/conf/template directory, enter the new prefix here.

You can find a description of the template files in Download manifest.

The default value is pingone-mfa.

Messages Files

Identifies the customizable language-pack file that the adapter uses to show messages on the templates.

If you customize the pingone-mfa-messages.properties file name in the /server/default/conf/language-packs directory, enter the new name here.

The default value is pingone-mfa-messages.

Prompt Users to Set Up MFA

Determines whether users with no authentication methods are prompted to add one.

Select this if you are Enabling the MFA setup prompt.

This checkbox is cleared by default.

Allow Users to Skip MFA Setup

Determines whether the MFA setup prompt includes a Skip option.

Consider selecting this if you are Enabling the MFA setup prompt.

This allows the user to sign on without setting up MFA.

This checkbox is cleared by default.

Allow Users to Manage Additional Authentication Methods

Determines whether users can add another authentication method or remove an existing one during sign-on.

The user must sign on with their existing authentication method first.

This checkbox is cleared by default.

Provision Users

If a user does not already exist in PingOne, the adapter provisions the user to PingOne.

Provision Authentication Methods

Determines whether the adapter adds authentication methods based on the user’s SMS Attribute, Voice Attribute, WhatsApp Attribute, and Email Attribute values.

Update Authentication Methods

This setting allows the adapter to automatically add new authentication methods for existing users.

Consider selecting this if you are Enabling user and authentication method provisioning.

During sign on, the adapter compares the user’s authentication methods in PingOne to the user’s SMS Attribute, Voice Attribute, WhatsApp Attribute, and Email Attribute values in the PingFederate authentication policy. If any new values are available for the user, the adapter adds them as authentication methods in PingOne.

The PingOne MFA IdP Adapter only adds authentication methods to PingOne.

If you want to synchronize authentication methods and other user attributes, use the PingOne Connector provided in the PingOne Integration Kit. Learn more in Known issues and limitations.

This checkbox is selected by default.

Overwrite Authentication Methods Configurations

If the adapter identifies new values for SMS, voice, WhatsApp, or email devices, this setting determines whether the adapter replaces the existing methods with the new ones or just adds the new authentication methods. The following options are available:

None (default): When selected, the user’s existing SMS, voice, WhatsApp, and email authentication methods are not overwritten. New devices are added.
All (SMS, Voice, WhatsApp, and Email): When selected, all the user’s existing SMS, voice, WhatsApp, and email authentication methods that do not exist in the input are overwritten.
Specific Methods: When selected, the only devices that are overwritten are those of the same device type as a newly provided device. All other devices remain the same.

Applies only when Update Authentication Methods is selected.

Allow only predefined values for phone or email devices

This option allows you to limit the values to the email addresses and phone numbers stored for the user. If you enable the option, the relevant email address or phone number is already filled in when the user tries to add a device, and the user cannot modify the address or phone number.

Enable Cookie Based Tracking

When selected, the adapter tracks a previously authenticated FIDO security key or platform device in a cookie so that a user is not prompted again.

Use Password Config Attribute

Adds a Use Password button to the device selection screen.

The Use Password policy action automatically exits the user from the current flow when the user has no device to perform MFA and is not authenticated prior to reaching the adapter.

Bypass MFA For Device Management Attribute

Enter the name of an attribute in this field. The adapter checks for this attribute in the authentication policy. If the value is true, MFA is not required to perform device management operations.

The set default operation never requires MFA.

Do not set the value of this attribute to true if you only have one adapter in the authentication policy. This results in bypassing MFA in the authentication flow entirely, and can lead to a security breach.

We recommend only using this attribute if you have two consecutive adapters in an authentication policy. In this configuration, the first adapter should either not contain this attribute at all, or the value of the attribute should be set to false. Only the second adapter should contain this attribute with a value of true.

Username Attribute

Determines the username for users provisioned to PingOne.

This is used when Enabling user and authentication method provisioning.

If you identify users based on their PingOne username, leave this field blank. New users are named based on the "incoming user ID" set for the adapter in your PingFederate authentication policy.

If you identify users based on their PingOne user ID, enter the name of an authentication policy attribute. New users are named based on the attribute instead of the "incoming user ID".

This relates to step 5 in Adding PingOne MFA to your authentication policy.

Applies only when Provision Users is selected.

This field is blank by default.

SMS Attribute

This is used when Enabling user and authentication method provisioning or when Update Authentication Methods is selected.

Enter an attribute name in this field. The default value is sms.

When provisioning users or updating a user’s authentication methods, the adapter checks for phone numbers in each attribute that begin with this prefix. The adapter adds these phone numbers as SMS authentication methods in PingOne MFA, up to the maximum number of methods.

For example, in the PingFederate authentication policy, a user has three phone numbers in the following attributes:

sms-1
sms-2
sms-3

By entering sms in this field, the adapter adds all three phone numbers as SMS authentication methods in PingOne MFA.

If your attribute value source maps multiple values to the same attribute, multiple authentication methods will be created.

Voice Attribute

This is used when Enabling user and authentication method provisioning.

When provisioning users or updating a user’s authentication methods, the adapter checks for phone numbers in each attribute that begin with this prefix. The adapter adds these phone numbers as voice authentication methods in PingOne MFA. Follows the same general behavior as the SMS Attribute field.

Applies only when Update Authentication Methods is selected.

The default value is voice.

Email Attribute

This is used when Enabling user and authentication method provisioning.

When provisioning users or updating a user’s authentication methods, the adapter checks for email addresses in each attribute that begin with this prefix. The adapter adds these email addresses as authentication methods in PingOne MFA.

Follows the same general behavior as the SMS Attribute field.

Applies only when Update Authentication Methods is selected.

The default value is email.

WhatsApp Attribute

This is used when Enabling user and authentication method provisioning.

Follows the same general behavior as the SMS Attribute field.

Applies only when Update Authentication Methods is selected.

The default value is whatsapp.

Application ID for Authentication Code Flow

The application ID to use for authentication code based flow.

Default Authentication Method for Provisioned Users

This is used when Enabling user and authentication method provisioning.

When provisioning a new user to PingOne, the adapter sets the user’s default authentication method based on this setting.

For example, when set to SMS, the adapter checks for attributes according to the SMS Attribute field. The first matching attribute, such as sms-1, becomes the user’s default authentication method.

Applies only when Update Authentication Methods is selected.

You can find a related entry in Known issues and limitations.

The default selection is SMS.

User Not Found Failure Mode

When a user error occurs in PingOne, this setting determines whether the adapter blocks the user’s sign-on attempt.

User errors include the following:

User is disabled
User does not exist
The PingOne MFA service is disabled for the user

The default selection is Block user.

Service Unavailable Failure Mode

When PingOne doesn’t respond, this setting determines how the adapter handles the user’s sign-on attempt:

Bypass Authentication: The PingOne MFA IdP Adapter bypasses the user’s sign-on attempt.
Block User: The PingOne MFA IdP Adapter blocks the user’s sign-on attempt.

If you select Block User, ensure that the Show Error Screens checkbox is selected. Learn more about Show Error Screens in one of the following table entries.

The default selection is Bypass Authentication.

Change Authentication Method

Determines whether the adapter shows a "back" button that allows a user to select a different authentication method during a sign-on session.

If your PingOne authentication policy uses the Being a member of any of these populations or User Attributes requirements, set this to Deny. The features are not compatible.

This setting has no effect when the adapter is used through the PingFederate authentication API.

The default selection is Allow.

Show Success Screens

Determines whether the adapter shows a success page when the MFA step is successful.

This checkbox is selected by default.

Show Error Screens

Determines whether the adapter shows an error page when the MFA step generates an error.

This checkbox is selected by default.

Show Timeout Screens

Determines whether the adapter shows a "timed out" page when the MFA step times out.

This checkbox is selected by default.

Enable Audit Log

When selected, the adapter logs end-user browser details along with selected authentication method info such as device type, correlation ID, and device nickname in PingFederate’s audit log.

API Request Timeout

The amount of time in milliseconds that PingFederate allows when establishing a connection with PingOne MFA or waiting for a response to a request. A value of 0 disables the timeout.

If you don’t want to use the device integrity check, you can decrease this to 5000ms. You can find more information about the device integrity check in Authentication method management.

The default value is 12000.

Proxy Settings

Defines proxy settings for outbound HTTP requests.

The default value is System Defaults.

Custom Proxy Host

The proxy server host name to use when Proxy Settings is set to Custom.

This field is blank by default.

Custom Proxy Port

The proxy server port to use when Proxy Settings is set to Custom.

This field is blank by default.