PingID Administration Guide

Configuring offline MFA (RADIUS PCV)

Offline multi-factor authentication (MFA) allows users to authenticate if the PingID server is inaccessible. To circumvent unforeseen outages or network issues preventing users from signing on to access their applications, implement the offline MFA feature of the RADIUS Password Credential Validator (PCV).

Before you begin

  • Install the latest version of the PingID Integration Kit.

  • Have PingID RADIUS PCV 2.0 or later.

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

  • Have 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

To configure offline MFA, sign on to the PingFederate administrative console and configure the RADIUS PCV for offline authentication. This configuration includes settings to support different LDAP 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 directory.

Steps

  1. Sign on to the PingFederate administrative console.

  2. Click Server Configuration.

  3. In the Authentication section, click Password Credential Validators.

    Result:

    The Manage Credential Validator Instances window displays.

  4. Click PingID PCV (with integrated RADIUS server).

    Result:

    The RADIUS instance summary window displays.

  5. Click the Instance Configuration tab.

  6. Click Show Advanced Fields.

  7. Configure the offline authentication options.

    Parameter Description

    Authentication During Errors

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

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

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

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

    • Enforce Offline Authentication: Forces 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.

      • This parameter replaces Fail Login on PingID Technical Error, which is deprecated in PCV 2.0.

    Users Without a Paired Device

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

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

    • Block User: PingID blocks authentication attempts from users without paired mobile devices.

    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 you select Passive Offline Authentication or Enforce Offline Authentication in the Authentication During Errors section. For more information, see User directory for PingID offline MFA.

    LDAP Data Source

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

    Create Entry for Devices

    Creates 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.

    If selected, PingFederate creates objects of type pf-pingid-device per user, and adds the device list information in its pf-pingid-local-fallback attribute. Otherwise, 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.

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

    Encryption Key for Devices

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

    If the admin changes the encryption key, all users must 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.

    Search Base

    The location in the directory from which the user directory search begins. Use when the offline authentication attributes are stored on the user entry in the main user directory. It contains the value of the Search Base field in the relevant Password Validator Instance Configuration, and the PCV Search Base parameter value must be identical to that.

    Applicable only when pf-pingid-local-fallback is added to the user object.

    Search Filter

    The basis of what to filter when the device list is stored on the user’s object in the user directory. The Search Filter parameter value must be identical to the Search Base field in the relevant Password Validator Instance configuration.

    You can use ${username} as part of the query. For example (for Active Directory), sAMAccountName=${username}.

    Applicable only when pf-pingid-local-fallback is added to the user object.

    Scope of Search

    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:

    • One level: search only in the defined branch and not in its subtrees.

    • Subtree: search in the defined branch and all of its subtrees.

      Applicable only when pf-pingid-local-fallback is added to the user object.

    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.

    • You can use either the Distinguished Name Pattern setting or the set of the Search Base, Search Filter and Scope of Search configuration settings above.

    • Distinguished 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.

    State Attribute

    State Attribute overrides 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 is blocked from performing the PingID offline MFA flow and denied access.

    • Empty: the user attribute set in the directory won’t be used during offline authentication.

      The exact name of the attribute configured in this field must also be added in the Extended Contract tab of the relevant Delegate PCV.

    PingID Heartbeat Timeout

    The duration of time in seconds that the adapter waits for the heartbeat calls to the PingID service, before falling back to the Authenticating During Errors feature. If left empty, the default value is 30 seconds.

  8. Click Done.

    Result:

    The Manage Credential Validator Instances window is displayed.

  9. Click Save to persist the updated configuration.