PingOne

Troubleshooting an LDAP gateway instance

If the gateway instance is not healthy, use the information in this section to troubleshoot any issues.

The following information applies to the various gateway deployment scenarios. You can use the gateway details page, gateway logs, or Splunk reports to identify issues. Learn more in Verifying a gateway instance and Monitoring activity with Splunk.

Users receive an error when signing on or changing their password

A user receives the following error message when signing on or trying to change their password:

A system error occurred when accessing your account for authentication. Contact your administrator.

This error can indicate that the user’s account needs to be updated in the external Lightweight Directory Access Protocol (LDAP) directory server. Check the user’s account in the external directory server. If you have an LDAP gateway configured, ensure that it is properly configured.

I want to view the audit logs

You can view logs to get detailed information about the Gateway service. The method to do so varies depending on your gateway configuration.

Gateway as a standalone service

By default, log files are saved to the ./logs directory on the computer running the gateway. Log files roll over by date.

To view the logs, locate the ./logs directory. The logs are namedGatewayStandalone.yyyymmdd.log

Gateway as a Windows service

By default, log files are saved to the ./logs directory on the computer running the gateway. Log files roll over by date.

To view the logs, locate the ./logs directory. The logs are named:

  • GatewayService.yyyymmdd.log

  • GatewayWrapper.yyyymmdd.log

    The GatewayWrapper.yyyymmdd.log file mirrors the console output of the standalone version, with additional logs.
Gateway as a Docker container

To view logs for a Docker container, run the following command:

docker logs  <container ID or name>

My logs aren’t showing enough information

You can enable verbose logging to get more detailed logs for the Gateway service. The method to do so varies depending on your gateway configuration.

The following steps were validated with PingOne LDAP Gateway version 2.3.3.
Gateway as a standalone service

By default, the log level is set to INFO, which includes errors and general information for the service. For more verbose logs, set the log level to DEBUG, which includes all possible information for the service.

  1. If the PingOne LDAP Gateway service is running, stop it.

  2. Locate the ./config/run.properties file.

  3. Locate the LOG_LEVEL parameter.

  4. Change the parameter to LOG_LEVEL=DEBUG.

  5. Restart the PingOne LDAP Gateway service.

You can also change the formatting of the console output.

  1. If the PingOne LDAP Gateway service is running, stop it.

  2. Locate the ./config/logback.xml file.

  3. Follow the instructions in the file to enable more detailed logs in the console.

  4. Restart the PingOne LDAP Gateway service.

Gateway as a Windows service

Use the LOG_LEVEL parameter to configure the logging settings. By default, the log level is set to INFO, which includes errors and general information for the service. For more verbose logs, set the log level to DEBUG, which includes all possible information for the service.

  1. Locate the ./config/run.properties file.

  2. Locate the LOG_LEVEL parameter.

  3. Change the parameter to LOG_LEVEL=DEBUG.

  4. Run ./bin/windows/reinstall-service.bat.

  5. Press the Windows + R keys.

  6. Enter services.msc to open the Windows Services Controller.

  7. Locate the PingOne LDAP Gateway service and start it.

The Ping Identity Gateway console opens and shows detailed logs.

Gateway as a Docker container

Use the Dlogger.console.level and LOG_LEVEL parameters to configure the logging settings.

Use the following Docker run command:

-e JAVA_OPTS="-Dlogger.console.level=DEBUG" -e LOG_LEVEL=DEBUG

You can also use Splunk to monitor a gateway connection. Learn more in Monitoring activity with Splunk.

My connection is taking too long to resolve

If your connection is taking a long time, check the following:

  • If the connection is configured with a string host name, try using an IP address instead.

  • On the server that you want to connect to, ensure that the desired port is open.

  • Ensure there aren’t any routing issues in your infrastructure that could affect the ability of the gateway server to reach the LDAP server or Remote Authentication Dial-In User Service (RADIUS) client.

  • Sometimes it can take several seconds for the connection information to be updated in the console user interface. Try refreshing the page to get the most current information.

I want to increase scalability

For high-availability applications or scalability, you can deploy multiple gateway instances. You can then run the Windows service, Docker container, or Java application on multiple servers.

When multiple gateway instances are connected to PingOne, PingOne maintains a list of the active gateway instance connection. PingOne will load balance based on each connection’s current load, prioritizing sending traffic to the connections with lower load and latency. If a gateway instance is not available, it is excluded from the list of active gateway instances.

Use a different credential for each deployed gateway instance. Using different credentials allows you to easily revoke access to individual gateway instances.

I’m getting a PKIX path building failed error

For LDAP gateway connections with provisioning, you might see the following error if the gateway connection is interrupted:

PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

If this error occurs, check the following:

  • Ensure that the LDAPS certificate was imported into PingOne correctly. Learn more in Importing an LDAP certificate to PingOne.

    1. Go to Integrations → Gateways, and click the gateway to open the details panel.

    2. Click the Connections tab, and then click Edit.

    3. Click the Allow TLS connections with untrusted certifications checkbox.

    4. Click Save.

    5. Re-test authentication.

    If authentication is successful when the gateway is set to ignore the LDAPS certificate, this confirms that there’s an issue with the certificate that the LDAP server is presenting.

  • Verify that traffic between the gateway and auth.pingone.com and api.pingone.com is uninterrupted (such as by proxies, firewalls, or SSL inspection). Learn more in Before configuring an LDAP gateway.

I’m getting an Active Directory password modify error

For LDAP gateway connections using Active Directory (AD), you might see password modify errors in your LDAP gateway client logs.

This error can appear as a failure to change a password using a service account in AD. The error appears as either of the following:

LDAP password change result requestId=be2f0fb3-a090-4bf5-ab9c-97a9e480f6e3,
resultCode=19 (constraint violation), resultDetails=LDAPResult(resultCode=19 (constraint violation),
diagnosticMessage='00000005: AtrErr: DSID-03191080, #1: 0: 00000005: DSID-03191080, problem 1005
(CONSTRAINT_ATT_TYPE), data 0, Att 9005a (unicodePwd)')
LDAP password change result requestId=be2f0fb3-a090-4bf5-ab9c-97a9e480f6e3,
resultCode=50 (insufficient access rights), resultDetails=LDAPResult(resultCode=50 (insufficient access rights),
diagnosticMessage='00000005: SecErr: DSID-031A11B9, problem 4003 (INSUFF_ACCESS_RIGHTS), data 0')

Learn more about the recommended configuration for the service account in AD in Best practices for configuring Active Directory for LDAP gateways.