PingID Administration Guide

Installing the PingID Integration Kit for VPN

To use PingID multi-factor authentication (MFA) for VPN authentication, you must install the PingID Integration Kit.

Before you begin

For instructions specific to Windows Login Integration, see Installing PingID Integration Kit for PingFederate (Windows login).

PingID Integration Kit Requirements

Before you install the PingID Integration Kit:

  • Register for the PingID Enterprise service on PingOne.

  • Configure the PingID service and download the PingID properties file (see Managing the PingID properties file).

  • Ensure you have installed the relevant PingFederate version as follows:

    • Beginning with PingID Integration Kit 2.11, PingFederate 10.0 or later is required

    • Beginning with PingID Integration Kit 2.10, PingFederate 9.3 or later is required

    • Beginning with PingID Integration Kit 2.6, PingFederate 9.2 or later is required

    • Beginning with PingID Integration Kit 1.4, PingFederate 8.4 or later is required

    • PingID Integration Kit 1.3 or earlier: requires PingFederate 8.3 or earlier (minimum supported version PingFederate 7.3)

  • Ensure you have network access to your PingFederate installation.

  • Ensure you have administrator permissions on PingFederate.

  • Open ports:

    • 443 (outbound to Internet)

    • 1812 (UDP, to/from RADIUS clients)

      Port 1812 is required only if you plan on using the password credential validator (PCV) for RADIUS. This is the default port for RADIUS, but you also have the option of setting a different port number for the RADIUS client and RADIUS PCV. To change the port for the PCV, use the RADIUS Server Authentication Port option.

    For further details about required web access, see PingID required domains, URLs, and ports.

About this task

The PingID Integration Kit is bundled as part of PingFederate 8.2 and later. If you have installed a recent version of PingFederate, no further action is required.

If you are doing any of the following, you’ll need to install the integration kit manually:

  • Using an earlier version of PingFederate.

  • Updating the PingID Integration Kit.

  • Installing the optional PingID offline MFA feature. PingID offline MFA requires that device information be stored on the user directory for retrieval when PingID cloud service is offline. If your organization requires the PingID offline MFA feature, configure the user directory. For more information, see User directory for PingID offline MFA.

    • PingID Integration Kit 2.0 and later is required for PingID offline MFA.

    • The setup of the prerequisite user directory for PingID offline MFA should be implemented before you stop the PingFederate server for deployment of the upgrade.

For more information about offline MFA, see PingID Offline MFA.

Steps

  1. Download and extract the PingID Integration Kit package from https://www.pingidentity.com/en/resources/downloads/pingid.html.

  2. Optional: If you are installing PingID offline MFA, set up the user directory. Sample scripts for Active Directory are supplied in Integration Kit 2.0 and later. You can modify these scripts for specific implementations. Choose one of the following methods to prepare the user directory for storage of the device information.

    Method Setup with ldif scripts (Active Directory only) Manual directory setup for all types of directories

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

    Update the <Your Location> parameter to the location of your full DN for schemas, and then run them. In the ldif folder:

    • deviceAttribute.ldif

    • addDevicesToUser.ldif

      If you are using Active Directory, execute the supplied ldif scripts with the following command line instruction: ldifde -i -f ${scriptname}

    1. Create a new user state attribute, and link it to the user class as an optional attribute:

      • The User State attribute name is optional. We recommend pf-pingid-state.

      • Attribute properties:

        • Type: Unicode String

        • Size: 0-64.

        • Object UID: 1.3.6.1.4.1.28867.9.2.37

    2. Create a new device list attribute in the directory called pf-pingid-local-fallback, and link it to the user class as an optional attribute:

      • The name of this device list attribute (pf-pingid-local-fallback) is mandatory.

      • Attribute properties:

        • Type: Unicode String

        • Size: 0-inf (unlimited size).

        • Object UID: 1.3.6.1.4.1.28867.9.2.36

    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.

    Run the following scripts located in the ldif folder:

    • deviceAttribute.ldif

    • createDeviceClass.ldif

    To create a specific organizational unit (OU) to store users’ device information, run the deviceOrgUnit.ldif script to create an OU with CN=PingID-devices.

    • You must specify where to save new objects in the plugin configuration.

    • You can either use an existing OU or create a new one.

    • The name PingID-Devices is not mandatory. The script may be edited to change the name.

    • If you are using Active Directory, execute the supplied ldif scripts with the following command line instruction: ldifde -i -f ${scriptname}

    1. Create a new User State attribute, and link it to the user class as an optional attribute:

      • The User State attribute name is optional. We recommend pf-pingid-state.

      • Attribute properties:

        • Type: Unicode String

        • Size: 0-64.

        • Object UID: 1.3.6.1.4.1.28867.9.2.37

    2. Create a new device list attribute in the directory called pf-pingid-local-fallback:

      • The name of this device list attribute (pf-pingid-local-fallback) is mandatory.

      • Attribute properties:

        • Type: Unicode String

        • Size: 0-inf (unlimited size).

        • Object UID: 1.3.6.1.4.1.28867.9.2.36

    3. Create a new device class in the directory called pf-pingid-device:

      • The name of this device list class (pf-pingid-device) is mandatory.

      • Class properties:

        • Object UID: 1.3.6.1.4.1.28867.9.1.3

        • Possible superiors: container, organizationalUnit

        • May contain the pf-pingid-local-fallback attribute.

        • In some cases to prevent a schema issue, you may need to add an identifying attribute to the pf-pingid-device object class, such as cn.

    4. Device list container: Create a new OU in the directory. The OU can have any name. We recommend PingID-Devices.

    Active Directory only:

    For both of the above storage methods, scripts are provided for setting up PingID offline MFA bypass or block state of the user in the directory. For more information on the state attribute, see User directory for PingID offline MFA.

    • To create the state attribute and add the attribute to the user object class, run the stateAttribute.ldif and addStateToUser.ldif scripts.

  3. On the PingFederate host, stop the PingFederate server.

  4. Navigate to the <pf_install>/server/default/deploy directory and remove the PingIDRadiusPCV-<version>.jar file.

    If you are running PingID Integration Kit earlier than 1.5, remove the following files:

    • pf-pingid-idp-adapter-<version>.jar

    • common-mfa-<version>.jar

    • gson-<version>.jar

    • jose4j-<version>.jar

  5. Copy the PingIDRadiusPCV-<version>.jar from the new pf-pingid-integration-kit-<version>/pf-pingid-pcv-<version>/dist directory to the <pf_install>/server/default/deploy directory.

  6. Restart the PingFederate server.

  7. If PingFederate is deployed on clustered servers, repeat these steps for all PingFederate nodes.