PingOne

Upgrading an LDAP gateway

Upgrade your LDAP gateway to keep your on-premise data accessible, secure, and performing well. Stay current to access essential security patches, new features, and simplified management tools.

Before you begin

  • Back up your current configuration and copy your existing run.properties file to a safe location.

  • If you need to maintain a historical record of gateway activity, you should also back up your log files before deleting the original directory.

Docker container

Upgrading in a Docker environment

To upgrade in a Docker environment, launch the latest Docker image version and verify its connection in PingOne before removing the legacy container.

Steps

  1. In the PingOne admin console, go to Integrations > Gateways and click the appropriate LDAP gateway.

  2. Click the Download tab.

  3. In the Instructions section, copy the Docker command and paste it into a file or the command prompt.

  4. Modify the copied Docker command to accept the EULA (PING_IDENTITY_ACCEPT_EULA=yes) and provide the new or existing gateway credential.

    The following example shows the modified command. Ensure that you replace <GATEWAY_CREDENTIAL> with your actual gateway credential. Running this command automatically pulls the new Docker image and runs the container.

    docker run --init -e PING_IDENTITY_ACCEPT_EULA=yes -e gatewayCredential=<GATEWAY_CREDENTIAL> pingidentity/pingone-ldap-gateway:<version>

  5. After you verify that the new gateway’s connection status is active in the PingOne admin console, remove the old version.

    docker stop <container_name>
docker rm <container_name>

  6. On the Overview tab, delete any credentials that are no longer in use.

    This reduces the risk of unauthorized access if an old credential file is compromised.

Standalone Java application

Upgrading in a standalone Java application

To upgrade in a standalone Java application, download the updated gateway client package, configure the run.properties file, and run the Java application.

Steps

  1. In the PingOne admin console, go to Integrations > Gateways and click the appropriate LDAP gateway.

  2. Download the latest gateway client package from the Download tab.

  3. Create a new directory for the version and extract the package in the new directory.

  4. Open the run.properties file from your current installation.

  5. Copy the credentials and environment settings into the run.properties file in the new directory.

  6. In the new directory, open a terminal or command prompt and run the launch script located in the /bin directory using the following commands:

    • Windows: run.bat

    • macOS or Linux: sh run.sh

      At this point, both the old and new gateway clients will be connected to PingOne simultaneously.

  7. To verify the gateway connection, check the gateway instance version in the PingOne admin console.

    1. Navigate to the gateway configuration and view the Overview > Instance details section.

  8. After you’ve confirmed the new client is working, shut down the old Java process and archive the old directory.

Windows service

Upgrading a Windows service

To upgrade a Windows service, unregister the old service version and register the new one.

Steps

  1. In the PingOne admin console, go to Integrations > Gateways and click the appropriate LDAP gateway.

  2. Click the Download tab.

  3. Download the zip archive for the latest version.

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

  5. Configure the run.properties file located in the config directory.

    1. Accept the end-user license agreement (EULA) and provide the gateway credentials for the service to start.

    2. Review the file to ensure configurations are updated. For example, if your network requires a proxy, those settings must be reapplied here.

      For reference, the file path typically looks like C:\Program Files\Ping Identity\pingone-ldap-gateway-[VERSION]\config\run.properties.

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

    • Start the Services system application and find the old 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 the C:\Program Files\Ping Identity\pingone-ldap-gateway-2.3.0\bin\windows directory.

    • Run the uninstall-service.bat file for the old LDAP gateway service, without any parameters. The underlying directories and files aren’t removed. Make backup copies and remove the files as needed.

  7. After you’ve uninstalled the old version, you can finish installing the new one.

    • Locate the install-service.bat file for the LDAP gateway service.

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

      By design, the install-service.bat file doesn’t 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 service.

Zero downtime

Upgrading with zero downtime

To perform a zero-downtime upgrade, run the new gateway instance in parallel with the legacy version and verify the transition before you remove the old client.

Steps

  1. In the PingOne admin console, go to Integrations > Gateways and click the appropriate LDAP gateway to open the details panel.

  2. Click the Download tab.

  3. Click the link to download the .zip archive for the latest version.

  4. Extract the files into a new directory separate from your current version.

  5. Open the run.properties file in the new directory. The file contains clearly marked parameters, and the order of the properties doesn’t matter.

    1. Locate the EULA_ACCEPTED property and set it to true (EULA_ACCEPTED=true).

    2. Locate the gateway credential property and provide the required credentials.

    3. Copy any custom settings from your old run.properties file, such as proxy configurations or specific LDAP search parameters.

  6. Launch the new gateway client while the old one is still running.

  7. Verify the connection in the PingOne admin console, and stop the old gateway client.

Verification

Always verify the upgrade using one of the following methods:

  • Check the version of the instance.

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

    2. Click the appropriate gateway to open the detail panel and then click Overview.

  • Check the gateway logs in Docker or the installed directory.