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 thebin
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
-
In the PingOne admin console, go to Integrations → Gateways and locate the appropriate gateway.
-
Click the gateway name to expand the gateway details.
-
Click the Download tab.
-
In the Standalone section, review the prerequisites and instructions.
-
In the Instructions section, click the download link for the gateway bundle.
If prompted, complete the sign-on process.
Result:
The download begins.
-
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
. -
Follow the instructions in the
README.txt
file to configure therun.properties
file, including providing the gateway credential information.The
run.properties
file is located in theconfig
directory. For example:C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\config
. -
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 thebin/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.
-
-
Sign on to Windows with administrator privileges.
-
Start a command prompt or PowerShell.
-
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. -
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
-
Sign on to Windows with administrator privileges.
-
Start the Services system application and stop the PingOne LDAP Gateway service.
-
Locate the
uninstall-service.bat
file.-
In the Services system application, locate the LDAP Gateway service.
-
Right-click and select Properties.
-
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 theC:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows
directory.
-
-
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
-
In the PingOne admin console, go to Integrations → Gateways.
-
Click the appropriate gateway entry to open the details panel.
-
Click the Download tab.
-
Click the download link to download the ZIP archive for version 2.3.1.
-
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
. -
Configure the
run.properties
file, including providing the gateway credential information.The
run.properties
file is located in theconfig
directory. For example:C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.1\config
. -
Uninstall the old version of the gateway before installing the new one.
-
Start the Services system application and find the LDAP Gateway 2.3.0 service.
-
Right-click and select Properties.
-
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 theC:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows
directory. -
Optional: Start the Services system application and stop the LDAP Gateway 2.3.0 service.
-
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.
-
-
After you have uninstalled the old version, you can finish installing the new one.
-
Locate the
install-service.bat
file for the LDAP Gateway 2.3.1 service. -
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. -
In the Services system application, start the new PingOne LDAP Gateway 2.3.1 service.
-