PingID Administration Guide

Installing the PingID Integration Kit for PingFederate

If your organization wants to use PingID as an authentication solution for federated single sign-on (SSO) with PingFederate, you must install the PingID Integration Kit.

Before you begin

For instructions specific to the 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

If you are using PingFederate 8.2 or later, the PingID Integration Kit is bundled as part of the PingFederate installation.

If you’re doing any of the following, you must install the integration kit manually:

  • Updating your current version of the PingID Integration Kit to a newer version.

  • Using a version of PingFederate earlier than 8.2.

  • Installing the optional PingID Offline MFA feature. PingID offline MFA requires that device information be stored on the user directory for retrieval when PingID is offline. You must configure your organization’s user directory to use this feature. For more information, see User directory for PingID offline MFA.

    Offline MFA requires the PingID Integration Kit 2.0 or later.

To install the integration kit to integrate PingID with your VPN, see Installing the PingID Integration Kit for VPN.

Steps

  1. Download and extract the PingID Integration Kit package from the Integrations section of the PingID download page at https://www.pingidentity.com/en/resources/downloads/pingid.html.

  2. Optional: If you are installing PingID offline MFA, set up the user directory by choosing one of the following methods to prepare the user directory for storage of the device information.

    For both of the following device storage methods, scripts are provided for setting up PingID offline MFA bypass or block state of the user in the directory. The state attribute is described in greater detail in User directory for PingID offline MFA.

    Sample scripts for Active Directory are supplied in Integration Kit 2.0 and later. You can modify these scripts for specific implementations.

    Choose from:

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

      Setup with LDIF scripts (Active Directory only) Manual directory setup for all directory types

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

      • deviceAttribute.ldif

      • addDeviceToUser.ldif

        If you are using Active Directory, run 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 can have any name. 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 namedpf-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.

      Setup with LDIF scripts (Active Directory only) Manual directory setup for all directory types

      Run the following scripts located in the ldif folder:

      • deviceAttribute.ldif

      • createDeviceClass.ldif

      If you want 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 in the plugin configuration where to save the new objects.

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

      • The name PingID-Devices is not mandatory. You can edit the script 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 can have any name. 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 named 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 named 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

          • Can 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 and give it a descriptive name, such as PingID-Devices.

      1. For Active Directory only, run the stateAttribute.ldif and addStateToUser.ldif scripts to create the state attribute and add the attribute to the user object class.

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

  4. Remove the relevant files from the PingFederate directory, according to the version of the integration kit you are currently using:

    Choose from:

    • PingID Integration Kit 2.0 or later

    • In the <pf_install>/server/default/deploy directory, remove the pf-pingid-idp-adapter-<version>.jar and pingid-web.war files.

    • In the <pf_install>/server/default/conf/template directory, remove the pingid-offline.auth.login.template.html file.

    • In the <pf_install>/server/default/conf/language-packs directory, remove the pingid-offline-auth-messages-<language> files.

    • PingID Integration Kit 1.5-2.0

    • In the <pf_install>/server/default/deploy directory, remove the pf-pingid-idp-adapter-<version>.jar file.

    • PingID Integration Kit earlier than 1.5

      In the <pf_install>/server/default/deploy directory:

    • Remove the pf-pingid-idp-adapter-<version>.jar file.

    • Remove the common-mfa-<version>.jar file.

    • Remove the gson-<version>.jar file.

    • Remove the jose4j-<version>.jar file.

  5. Copy the following files from the new pf-pingid-integration-kit-<version>/pf-pingid-idp-adapter-<version>/dist directory to the <pf_install>/server/default/deploy directory:

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

    • pingid-web.war

  6. Optional: If you are installing and configuring only for PingID offline MFA, before you restart the PingFederate Server:

    1. Copy the pingid.offline.auth.login.template.html file to the <pf_install>/server/default/conf/template directory.

    2. Configure the PingID offline MFA feature for language support:

      • Go to <pf_install>/server/default/conf/language-packs

      • For each required language:

        1. Copy the pingfederate-messages.properties file to the pingfederate-messages_<language>_<region>.properties directory according to the locales supported by Java. For example, pingfederate-messages_fr_CA.properties.

        2. Append the content of the language file from the dist/language-packs directory to the appropriate properties file.

          cat pingfederate-messages.properties pingid-offline-auth-messages_fr_CA.properties >> pingfederate-messages_fr_CA.properties

          • A minimum of one language must be configured, including English.

          • Localization is supported for:

            • English,

            • French (EU)

            • French (Canadian)

            • German

            • Japanese

            • Chinese

            • Dutch

            • Italian

            • Korean

            • Portuguese

            • Russian

            • Spanish

            • Thai

  7. Restart the PingFederate server.

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