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
-
Download and extract the PingID Integration Kit package from https://www.pingidentity.com/en/resources/downloads/pingid.html.
-
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 theldif
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}
-
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
-
-
-
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 withCN=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}
-
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
-
-
-
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
-
-
-
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 ascn
.
-
-
-
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
orblock
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
andaddStateToUser.ldif
scripts.
-
-
On the PingFederate host, stop the PingFederate server.
-
Navigate to the
<pf_install>/server/default/deploy
directory and remove thePingIDRadiusPCV-<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
-
-
Copy the
PingIDRadiusPCV-<version>.jar
from the newpf-pingid-integration-kit-<version>/pf-pingid-pcv-<version>/dist
directory to the<pf_install>/server/default/deploy
directory. -
Restart the PingFederate server.
-
If PingFederate is deployed on clustered servers, repeat these steps for all PingFederate nodes.