PingID Administration Guide

Configuring PingID Proxy for the PingID desktop app

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

Before you begin

To obtain the latest version of the SetProxyParams script, see https://github.com/pingidentity/pingid-desktop-application.

Steps

  1. In the PingID admin portal, go to Setup → PingID → Configuration.

  2. In the Use Proxy For Desktop field, select one of the following options, and then click Save.

    Choose from:

    • Enable: Enable the use of PingID desktop app with the enterprise proxy, according to the mode configured in the SetProxyParams script.

    • Disable: Disable use of PingID desktop app with a proxy. This is the default selection.

      A screen capture of the Use Proxy For Desktop section.

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

  3. If Use Proxy For Desktop is set to Enable, modify the SetProxyParams script.

    The SetProxyParams script is configured at machine level. If there are multiple instances of the desktop app 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 with the enterprise proxy. The proxy toggle does not appear on the desktop app 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 menu, to accommodate authentication in different work modes, from within the enterprise network, or externally. For more information, see Enabling or disabling your proxy for PingIDdesktop.

      • Windows:

        SetProxyParams.bat host port [username] [password]

      • Mac:

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

    • Disabled mode: Disables use of the desktop app 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 does not require credentials.

      password

      Mandatory if the proxy requires credentials.

      Empty if the proxy does not require credentials.

      -r

      Mandatory for restrictive mode.

      Empty for permissive mode.

    To configure Proxy Auto Configuration (PAC) for the desktop app, see Configuring Proxy Auto Configuration for the PingID desktop app.

    To configure Kerberos proxy authentication for the desktop app, see Configuring Kerberos proxy authentication for the PingID desktop app.

  4. Optional: To allow the PingID desktop app to work with a proxy, using a self-signed certificate or local CA-signed certificate, complete the following steps:

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

    2. Download a copy of the certificate that is 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

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

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

Configuring Proxy Auto Configuration for the PingID desktop app

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. Open the Internet Explorer configuration window and click the Network tab.

      2. In the Use Automatic Configuration Script field, enter the URL of the PAC file you want to use. Click OK.

    • Mac:

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

      2. Select the Automatic Proxy Configuration check box.

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

    2. Open the PingID log file.

      Result:

      If the PingID desktop app 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, either the proxy is not working correctly, or there is a configuration problem.

Configuring Kerberos proxy authentication for the PingID desktop app

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

Before you begin

Install the PingID desktop app 1.5.2 or later.

About this task

The PingID desktop app 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 might vary according to the KDC configuration.

Steps

  1. Ensure that a Kerberos token is initialized on the user’s operating system.

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