PingOne

Running a standalone gateway as a Windows service

You can run the PingOne Lightweight Directory Access Protocol (LDAP) gateway as a standalone Windows service. You’ll do this by downloading a ZIP archive and adding the service to a computer running Windows. This functionality is available in LDAP Gateway version 2.3.0 and later.

Before you begin

  • If you have a valid gateway credential, have it ready. Alternatively, you can create a new credential on the Overview tab in the gateway details. See Creating or deleting a gateway credential.

  • Install Java version 17.0.8 or later or Java version 21 LTS or later on the computer that will run the gateway.

  • Create a JAVA_HOME system environment variable that points to the directory that contains the bin directory from the Java distribution.

Directory structure

You’ll download the PingOne LDAP gateway software in a ZIP archive. Most extract utilities will extract the files to a directory with a pattern of pingone-ldap-gateway-<version>. This directory structure is part of the ZIP archive. For best results, do not rename the pingone-ldap-gateway-<version> directory.

The archive extracts the files with the following directory structure:

Parent directory

C:\Program Files\Ping Identity

LDAP Gateway directory

C:\Program Files\Ping Identity\pingone-ldap-gateway-<version>

run.properties location

C:\Program Files\Ping Identity\pingone-ldap-gateway-<version>\config

Batch files location

C:\Program Files\Ping Identity\pingone-ldap-gateway-<version>\bin\windows

For more information, see:

Adding the LDAP gateway service

Download the .zip archive and extract it to the computer that will run the gateway.

Steps

  1. In the PingOne admin console, go to Integrations → Gateways and locate the appropriate gateway.

  2. Click the gateway name to expand the gateway details.

  3. Click the Download tab.

  4. In the Standalone section, review the prerequisites and instructions.

  5. In the Instructions section, click the download link for the gateway bundle.

    If prompted, complete the sign-on process.

    Result:

    The download begins.

  6. Extract the .zip archive to the computer that will run the gateway.

    We recommend that you use a common location as the parent directory, such as C:\Program Files\Ping Identity.

  7. Follow the instructions in the README.txt file to configure the run.properties file, including providing the gateway credential information.

    The run.properties file is located in the config directory. For example: C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\config.

  8. Optional: To configure an LDAP Gateway client application to use a forward web proxy server to handle traffic between the gateway and PingOne, provide access information into the run.properties file.

    • To add the web proxy details after installing the LDAP gateway client application as a Windows service, update the run.properties file, and then run the bin/windows/reinstall-service.bat file using an account with administrator privileges.

    • You must also configure the web proxy settings locally per each running instance. For example, if you’re running two gateway client applications, you must configure web proxy settings in both instances.

    • Digest authentication does not support international characters.

    • Basic authentication requires configuration in the proxy server to support international characters.

  9. Sign on to Windows with administrator privileges.

  10. Start a command prompt or PowerShell.

  11. Run the install-service.bat file without any parameters.

    By design, the install-service.bat file does not start the service automatically after completion. However, the service is configured to start automatically at the next and subsequent restarts of the Windows operating system.

  12. In the Services system application, start the PingOne LDAP Gateway service.

Removing the LDAP gateway service

Use the following information to remove the PingOne LDAP Gateway service.

Steps

  1. Sign on to Windows with administrator privileges.

  2. Start the Services system application and stop the PingOne LDAP Gateway service.

  3. Locate the uninstall-service.bat file.

    1. In the Services system application, locate the LDAP Gateway service.

    2. Right-click and select Properties.

    3. Note the Path to executable value.

      For example, if the value is

      C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows\ldap-gateway-windows-x86-64.exe -s C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows\PingOneLdapGatewayService.conf

      then you can find the uninstall-service.bat file in the C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows directory.

  4. Run the uninstall-service.bat file without any parameters. The underlying directories and files are not removed. Make backup copies and remove the files as needed.

Upgrading the PingOne LDAP Gateway

Use the following information to update the PingOne LDAP Gateway, such as from version 2.3.0 to version 2.3.1. You’ll uninstall the old version before installing the new one.

Steps

  1. In the PingOne admin console, go to Integrations → Gateways.

  2. Click the appropriate gateway entry to open the details panel.

  3. Click the Download tab.

  4. Click the download link to download the ZIP archive for version 2.3.1.

  5. Extract the ZIP archive to the computer that will run the gateway.

    We recommend that you use a common location as the parent directory, such as C:\Program Files\Ping Identity.

  6. Configure the run.properties file, including providing the gateway credential information.

    The run.properties file is located in the config directory. For example: C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.1\config.

  7. Uninstall the old version of the gateway before installing the new one.

    1. Start the Services system application and find the LDAP Gateway 2.3.0 service.

    2. Right-click and select Properties.

    3. Note the Path to executable value.

      For example, if the value is C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows\ldap-gateway-windows-x86-64.exe -s C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows\PingOneLdapGatewayService.conf

      then you can find the uninstall-service.bat file in the C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows directory.

    4. Optional: Start the Services system application and stop the LDAP Gateway 2.3.0 service.

    5. Run the uninstall-service.bat file for the LDAP Gateway 2.3.0 service, without any parameters. The underlying directories and files are not removed. Make backup copies and remove the files as needed.

  8. After you have uninstalled the old version, you can finish installing the new one.

    1. Locate the install-service.bat file for the LDAP Gateway 2.3.1 service.

    2. Run the install-service.bat file without any parameters.

      By design, the install-service.bat file does not start the service automatically after completion. However, the service is configured to start automatically at the next and subsequent restarts of the Windows operating system.

    3. In the Services system application, start the new PingOne LDAP Gateway 2.3.1 service.