PingID Administration Guide

Configuring offline MFA (PingID Adapter)

Offline multi-factor authentication (MFA) allows users to authenticate when the PingID server is inaccessible.

Before you begin

Offline MFA allows users to authenticate when the PingID server is inaccessible. If your organization is using PingID as a primary or secondary mode of authentication for federated single sign-on (SSO), you can implement the offline MFA feature of the PingID adapter, so you can circumvent unforeseen outages or network issues preventing users from logging in to access their applications.

Before you configure offline MFA, make sure that you have the following:

  • PingID Adapter 2.0+ installed.

  • A user directory to store the user’s device information from PingID. For more information, see User directory for PingID offline MFA.

  • Unlimited Strength Java Cryptography Extension (JCE), which is required for supporting the 256 byte key size for cryptographic algorithms. Without it, the feature will return an exception related to the missing library and will not function.

About this task

Sign on to the PingFederate admin console and configure the PingID Adapter for offline authentication. The configuration includes settings that support different user directory deployment implementations, such as storing the user device lists on the user object, on a separate devices object, or in a different directory, separate from the user’s directory.

Steps

  1. Sign on to the PingFederate admin console.

  2. Click IdP Configuration.

  3. Click Adapters in the APPLICATION INTEGRATION section.

    The Manage IdP Adapter Instances screen is displayed.

  4. Click PingID Adapter (the adapter you previously installed, bundled with the PingID integration kit).

    The PingID Adapter summary screen is displayed.

  5. Click the IdP Adapter tab.

    The PingID Adapter configuration screen is displayed.

  6. Click Show Advanced Fields.

    The PingID Adapter advanced configuration options are displayed.

  7. Configure the PingID offline MFA options.

    Parameter Description

    LDAP SEARCH SCOPE

    The options for determining the width and depth of the search, when the device list is stored on the user’s object in the user directory:

    • OBJECT_SCOPE: Search only in the base object.

    • ONE_LEVEL_SCOPE: Search in the immediate children of the base object, but exclude the base object itself.

    • SUBTREE_SCOPE: Search the base object and all of it children.

    STATE ATTRIBUTE

    The STATE ATTRIBUTE is used to override how a specific user is authenticated during offline authentication. The value of this field is the name of the attribute configured in the directory. If the PingID services are unreachable, the value of STATE ATTRIBUTE is evaluated:

    • Bypass: The user bypasses PingID MFA.

    • Block: (Case insensitive) The user will be blocked from performing the PingID offline MFA flow and denied access.

    If this parameter is not populated, the behavior of the offline authentication for the user will be taken from the AUTHENTICATION DURING ERRORS block in the PingID Adapter configuration.

    PINGID HEARTBEAT TIMEOUT

    The duration of time in seconds that the adapter will wait for the heartbeat calls to the PingID service, before falling back to the AUTHENTICATING DURING ERRORS feature. If left empty, the default is 30 seconds.

    AUTHENTICATION DURING ERRORS

    Determines how to handle user authentication requests when PingID services are unavailable.

    • Bypass User: Accept the user’s first factor authentication, and bypass the PingID MFA flow when the PingID MFA service is unavailable.

    • Block User: Reject and block the user’s login attempt when the PingID MFA service is unavailable.

    • Passive Offline Authentication: Fallback to the PingID offline MFA flow when the PingID MFA service is unavailable. Users will be asked to scan a QR code with a mobile device previously registered with PingID to obtain an authentication code to authenticate.

    • Enforce Offline Authentication: Force PingID offline MFA flow regardless of the PingID MFA service availability.

    User devices are updated in the directory for bypass, block, and passive offline modes.

    USERS WITHOUT A PAIRED DEVICE

    When PingID services are unavailable, you can choose to bypass or block users who have no paired mobile device (pf-pingid-local-fallback attribute in user’s device list in the user directory).

    • Bypass User indicates users without paired mobile devices will bypass the PingID adapter in an authentication attempt.

    • Block User indicates users without paired mobile devices will have PingID block their authentication attempt.

    A user’s individual block or bypass State attribute in the user directory will override the USERS WITHOUT A PAIRED DEVICE definition.

    This configuration is only relevant if Passive offline authentication or Enforce offline authentication were chosen in the AUTHENTICATION DURING ERRORS field. See User directory for PingID offline MFA for more details.

    LDAP DATA SOURCE FOR DEVICES

    The user directory data source used for retrieving additional user attributes for PingID offline MFA. This is the datastore in which the users device list (pf-pingid-local-fallback attribute) is stored.

    CREATE ENTRY FOR DEVICES

    Create the device list entry in the data source if it does not exist. This is the configuration setting for how and when PingFederate will create PingID device entries of type pf-pingid-device.

    Applicable only when pf-pingid-local-fallback is added to pf-pingid-device.

    • Checked: PingID Adapter will create objects of type pf-pingid-device per user, and add the device list information in its pf-pingid-local-fallback attribute.

    • Unchecked: PingFederate will assume that the pf-pingid-device objects per user are being created by an external system, and will only modify the pf-pingid-local-fallback attribute attached to them when needed.

    ENCRYPTION KEY FOR DEVICES

    This field contains the base64url encoded HMAC256 encryption key to encrypt the users devices list before saving to the user directory. This field is optional. If this field is empty, the devices lists will be kept unencrypted and will be stored as plain text.

    If the admin changes the encryption key, all users will have to authenticate online at least once, in order for new device details to be kept locally, or else the behavior in an offline scenario will follow the USERS WITHOUT A PAIRED DEVICE setting.

    DISTINGUISHED NAME PATTERN

    The pattern used to save device entries. It points to the location in the directory in which the pf-pingid-device objects reside.

    • DISTIGUISHED NAME PATTERN must be used in either of the following scenarios:

      • When using more than one PCV or PingID Adapter instance with more than one configured PingID tenant.

      • When both the PCV and PingID Adapter are configured with more than one tenant.

    • This parameter is required only if offline authentication is enabled when the pf-pingid-local-fallback attribute is saved separately from the user object.

    HTML TEMPLATE

    The template to which the adapter redirects users when the PingID offline MFA flow is triggered. The default value is pingid.offline.auth.login.template.html. Templates are located at /server/default/conf/template.

    Choose one of the following methods to configure the LDAP DATA SOURCE FOR DEVICES to be used for offline authentication.

    Method Instructions

    Deployments where the device information is stored in an attribute on the user object class

    1. Set the LDAP DATA SOURCE FOR DEVICES field to the same data store as set in your LDAP DATA SOURCE.

    2. Leave the DISTINGUISHED NAME PATTERN field empty.

    3. Configure the remaining fields as necessary to comply with your organization’s policy decisions.

    Deployments where device information is stored in an attribute on an object separate from that of the user. This is the same process whether the device information is in the same directory as the user object, or in a separate directory.

    1. Populate the LDAP DATA SOURCE FOR DEVICES field:

      • If the devices object is in the SAME directory as the user object, set the LDAP DATA SOURCE FOR DEVICES field to the SAME data store as set in your LDAP DATA SOURCE.

      • If the devices object is in a DIFFERENT directory from the user object, set the LDAP DATA SOURCE FOR DEVICES field to a DIFFERENT data store than that selected in LDAP DATA SOURCE.

    2. Populate the DISTINGUISHED NAME PATTERN field with an appropriate pattern to specify where the device information is stored (for example: CN={username},OU=PingID-Devices,DC=myDomain,DC=com).

    3. Select CREATE ENTRY FOR DEVICES if you want the adapter to create NEW records for users’ devices, if they don’t already exist.

    The pingid_state attribute is included in the core contract of the PingID adapter. The attribute value can be used in the Authentication Policy to make policy decisions based on the following criteria:

    Criteria pingid_statevalue

    Success

    		 
    [.codeph]``service_available``
    		 
    {pingid} down, bypass
    		 
    [.codeph]``service_unavailable``

    Offline authentication success

    		 
    [.codeph]``offline_auth``

    Offline authentication success, state attribute bypass

    		 
    [.codeph]``offline_auth_state``

    Offline authentication success, users with unpaired device bypass

    		 
    [.codeph]``offline_auth_unpaired``

    Offline authentication success, user device data read error

    		 
    [.codeph]``offline_auth_unknown``

  8. Click Done.

    The Manage IdP Adapter Instances screen is displayed.

  9. Click Save to persist the updated configuration.

  10. To use OAEP padding together with RSA encryption during offline authentication:

    1. In PingFederate, go to Authentication → PingID Adapter.

    2. Click the IdP Adapter tab and then click Show advanced Fields.

    3. In the Offline Authentication Encryption drop-down list, select the relevant value, and then click Save.

      Possible values are OAEP (default) or None.

      • The Offline Authentication Encryption configuration settings are backward compatible. If Offline Authentication Encryption is configured in the PingID Adapter v2.12 or later, no update is required in the UI. If upgrading from an older PingID Adapter version although the configuration is saved during the upgrade, the UI OAEP padding value is not automatically updated. An error message appears in the UI until you update it manually.

      • If you are using a PingFederate cluster, you must carry out these steps on each server in order to use OAEP padding.

Testing PingID offline configuration

About this task

Conducting preliminary tests of the PingID offline configuration ensures the selected offline flow works in case of a PingID service failure.

To test PingID offline configuration:

Steps

  1. Change the PingID properties file to break the connection to the PingID server by opening the PingID Adapter configuration and changing the values in the PingID properties file.

    Make sure to keep a copy of the original file.

    You can alternately test the flow by setting the Enforce Offline MFA option without making changes to the properties file.

    1. Change the idp_url and authenticator_url.

      The original arguments are:

    The following are examples of changes you can make to the arguments to test the offline configuration:

  2. Start an online authentication.

    If the RADIUS password credential validator (PCV) is enabled, block all HTTP traffic to idpxnyl3m.pingidentity.com and authenticator.pingone.com on destination port 443 using your firewall or proxy server.

    Result:

    The selected MFA offline flow is triggered.