PingOne

PingID desktop app (legacy)

This section documents the legacy PingID desktop app. For the latest version of PingID desktop app, go to (Workforce only) Configuring the PingID desktop application

PingID desktop app (legacy) can be installed on a PC or Mac machine by the end user themselves, and they can use it to generate a one-time passcode (OTP) with which to authenticate.

PingID desktop app (legacy) uses the HMAC-based one-time password (HOTP) algorithm to generate the OTP.

Users must be online to pair the PingID desktop app (legacy) or change their PIN.

Before you begin

PingID desktop app (legacy) is available for the following platforms and versions:

  • Microsoft Windows 10 and 11

  • Microsoft Windows Server 2016 and 2019

  • Apple Mac OS X 11+

The PingID desktop app (legacy) does not run on an Apple Mac OSX virtual machine (VM).

The PingID desktop app (legacy) requires a minimum of 155 MB RAM and 212 MB free disc space.

Learn more about the user experience in the PingID End User Guide.

  • Different end users using the same PC have different PingID accounts and undergo a unique authentication process. Each end user only sees their own organizations.

  • When a user is registered to two different organizations, each organization’s administrators can only see the details of their own organization’s end users.

  • Roaming user profiles:

    • Roaming user profiles are available for the Windows version of PingID desktop app (legacy) 1.5.3 or later.

    • To enable roaming user profiles, users must be unpaired and any previous installation of the PingID desktop app (legacy) must be uninstalled.

    • All terminals available for roaming users must have the PingID desktop app (legacy) installed with user roaming profiles support enabled.

Enabling PingID desktop app (legacy) in MFA policy

Steps

Adding PingID desktop app (legacy) as an authentication method includes the following steps:

  1. Configure the MFA policy to include PingID desktop app (legacy). Learn more Configuring an MFA policy for strong authentication.

  2. (Optional) Configure the PingID desktop app (legacy) application if you want to:

    • Add a PIN to the PingID desktop app (legacy). This elevates security by preventing unauthorized users from accessing the PingID desktop app (legacy) on an unlocked machine.

    • Add a proxy.

Configuring the PingID desktop app (legacy) PIN

As an extra layer of security, you can require users to enter a 4 or 6-digit PIN code to access the PingID desktop app (legacy).

About this task

If you enable the PingID desktop app (legacy) security PIN:

  • Users are prompted to create a PIN code when they pair the desktop app (legacy). The PIN code must include at least 3 or 4 different digits for PIN lengths of 4 and 6 digits, respectively. Digits must not be in ascending or descending sequence, such as 1234 or 4321.

  • Users are prompted to enter the PIN code each time they launch the PingID desktop app (legacy).

  • The PingID desktop app (legacy) is locked after 3 minutes of inactivity, and the user must enter the PIN to unlock it.

  • In the event of three consecutive incorrect PIN entries, the user is blocked from accessing the app for 2 minutes. This applies to both the PIN entry and the PIN change windows. Lockdown takes effect from the time of the lock, no matter if the PingID desktop app (legacy) remains open or is closed and relaunched.

  • The PingID desktop app (legacy) must be online for a user to pair the app. However, a user who is offline can still create a PIN, enter the PIN to access the app, or change their PIN.

  • The PingID desktop app (legacy) must be online for a change in PIN configuration to take effect, such as enabling or disabling the PIN or changing its length.

  • If a user pairs the PingID desktop app (legacy) to more than one organization, the user must create only one PIN, according to the most restrictive organization requirements. For example:

    • If only one organization has enabled the Desktop Security PIN feature, the user is required to enter their PIN to use the PingID desktop app (legacy) for authentication to all organizations, including those which don’t require the PIN.

    • If one organization requires a 4-Digit PIN and a second organization requires a 6-Digit, the user will be required to enter a 6-digit PIN.

  • If the PIN code is already enabled, and the administrator changes the length of the PIN code required, users must first enter the app using the old PIN and then create a new PIN of the new length.

Steps

  1. Go to Applications > Applications.

  2. In the Applications list, select PingID Desktop (legacy).

  3. On the Configuration tab, click the Pencil icon and then select the Require desktop app security PIN checkbox.

  4. In the Desktop Security PIN section, click either 4-Digit or 6-Digit to indicate the PIN length.

  5. Click Save.

    Result:

    If an administrator edits the PingID desktop app (legacy) configuration to require a PIN code, changes are implemented at the user level according to the PingID version and the user flow.

    • Users installing the PingID desktop app (legacy) for the first time are prompted to create a PIN at the end of the desktop app pairing flow.

    • Users with the PingID desktop app (legacy) 1.4 or later already paired are prompted to define a PIN code the next time they open the app while online.

Next steps

Add the MFA policy to the MFA step in the relevant Authentication policy. Learn more in Adding a multi-factor authentication or PingID step.

Configuring PingID proxy for the PingID desktop app (legacy)

Configure the PingID desktop app (legacy) to support proxy for all enterprise internal communication to the internet on enterprise desktop and laptop machines.

Before you begin

You can get latest version of the SetProxyParams script at https://github.com/pingidentity/pingid-desktop-application.

Steps

  1. In PingOne, go to Applications > Applications.

  2. In the Applications list, select PingID Desktop (legacy).

  3. On the Configuration tab, click the Pencil icon.

  4. To enable the use of PingID desktop app (legacy) with the enterprise proxy, according to the mode configured in the SetProxyParams script, select the Use proxy for desktop app checkbox and then click Save.

    Even if the Use Proxy For Desktop setting is enabled enterprise-wide in the admin portal, administrators can require the desktop app (legacy) installations on specific desktops and laptops to always work without a proxy.

  5. Modify the SetProxyParams script, editing the relevant parameters.

    The SetProxyParams script is configured at machine level. If there are multiple instances of the desktop app (legacy) installed on a machine, the setting of the SetProxyParams is applied to all instances.

    Choose from:

    • Restrictive mode: Forces users to use the desktop app (legacy) with the enterprise proxy. The proxy toggle doesn’t appear on the desktop app (legacy) menu.

    • Windows:

      SetProxyParams.bat host port [username] [password] -r

    • Mac:

      sudo sh SetProxyParams.sh host port [username] [password] -r

    • Permissive mode: Provides users an option to enable or disable use of the proxy from the desktop app (legacy) menu, to accommodate authentication in different work modes, from within the enterprise network, or externally.

    • Windows:

      SetProxyParams.bat host port [username] [password]

    • Mac:

      sudo sh SetProxyParams.sh host port [username] [password]

    • Disabled mode: Disables use of the desktop app (legacy) with a proxy on specific devices.

    • Windows:

      SetProxyParams.bat disable

    • Mac:

      sudo sh SetProxyParams.sh disable

      Where:

      Parameter Description

      host

      Proxy host IP address or host name.

      port

      Proxy port number.

      username

      Mandatory if the proxy requires credentials.

      Empty if the proxy doesn’t require credentials.

      password

      Mandatory if the proxy requires credentials.

      Empty if the proxy doesn’t require credentials.

      -r

      Mandatory for restrictive mode.

      Empty for permissive mode.

  6. (Optional) Configure one of the following for PingID desktop app (legacy):

    • Proxy Auto Configuration (PAC).

    • Kerberos proxy authentication.

  7. (Optional) To allow the PingID desktop app (legacy) to work with a proxy, using a self-signed certificate or local CA-signed certificate:

    1. Ensure that the Java Development Kit (JDK) keytool utility is installed.

    2. Download a copy of the certificate that’s installed on the proxy in DER format, and then save it to the local hard drive.

    3. Open the integrated terminal and navigate to the Java Runtime Environment (JRE) security directory inside the PingID root directory.

      The default paths are:

      • Windows: C:\Program Files (x86)\Ping Identity\PingID\runtime\lib\security

      • Mac: /Applications/PingID.app/Contents/PlugIns/Java.runtime/Contents/Home/jre/lib/security

    4. Add the certificate to the JRE certificate trust store.

      keytool -import -keystore cacerts -file <certificate file> -storepass changeit

Next steps

If you haven’t yet enabled and configured PingID desktop app (legacy) as an authentication method in your MFA policy, you can find instructions in Configuring an MFA policy for strong authentication.

Configuring PAC for the PingID desktop app (legacy)

Proxy Auto Configuration (PAC) enables you to manage networks that have multiple proxies so that you can configure different proxy servers for different URLs and replace proxies dynamically by editing and updating the PAC file.

Steps

  1. On the relevant user’s machine, configure the PAC URL:

    Choose from:

    • Windows:

      1. Go to Start > Settings > Proxy and then clear the Automatically detect settings checkbox.

      2. Select the Use setup script checkbox, enter the PAC file address, and click Save.

    • Mac:

      1. Go to System Preferences > Network, click Advanced, and then go to the Proxies tab.

      2. Select the Automatic Proxy Configuration checkbox.

      3. In the Proxy Configuration File URL field, enter the URL of the PAC file that you want to use. Click OK.

  2. On the relevant user’s machine, configure the PingID desktop app (legacy) to work with PAC according to your operating system.

    Choose from:

    • Windows 32-bit: From the command line, enter "C:\Program Files\Ping Identity\PingID\ProxyHelperSetup.exe" -pac.

    • Windows 64-bit: From the command line, enter "C:\Program Files(x86)\Ping Identity\PingID\ProxyHelperSetup.exe" -pac.

    • Mac: In a terminal window, enter sudo /Applications/PingID.app/Contents/MacOS/ProxyHelperSetup -pac, and then enter the admin password when prompted.

  3. Test the communication with the proxy server:

    1. Pair the PingID desktop app (legacy).

    2. Open the PingID log file.

      Result:

    If the PingID desktop app (legacy) can communicate with PingID cloud server, the Proxy configuration is PAC entry appears during application startup. If there is no communication, indicated by an unknown error message when pairing the PingID desktop app (legacy), either the proxy is not working correctly, or there is a configuration problem.

Configuring Kerberos Proxy authentication for the PingID desktop app (legacy)

The PingID desktop app (Legacy) supports proxy authentication using the Kerberos protocol, delegating the machine credentials for authentication to the organizational proxy.

About this task

The PingID desktop app (Legacy) supports proxy authentication using the Kerberos protocol, delegating the machine credentials for authentication to the organizational proxy. The HTTP client uses Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) to negotiate the authentication method.

When Kerberos is the agreed protocol, the client uses a ticket generated by the Key Distribution Center (KDC) for the proxy authentication that can be used multiple times. The Kerberos ticket expiry period can vary according to the KDC configuration.

Steps

  1. Ensure that a Kerberos token is initialized on the user’s operating system, and then from the command line or terminal window, run klist to verify that a valid Kerberos token is available.

  2. From the command line or terminal window, enter the following command:

    Choose from:

    • Windows:

      "C:\Program Files(x86)\Ping Identity\PingID\ProxyHelperSetup.exe"
<host> <port> -kerberos

    • Mac:

      sudo /Applications/PingID.app/Contents/MacOS/ProxyHelperSetup
<host> <port> -kerberos

  3. From the command line or terminal window, enter the following command to test Proxy Auto Configuration (PAC) with Kerberos.

    Choose from:

    • Windows:

      "C:\Program Files(x86)\Ping Identity\PingID\ProxyHelperSetup.exe"
-pac -kerberos

    • Mac:

      sudo /Applications/PingID.app/Contents/MacOS/ProxyHelperSetup -pac -kerberos