Java Agents 2024.3

Troubleshooting

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to help you set up and maintain your deployments. For help, refer to Getting support.

When you are trying to solve a problem, save time by asking the following questions:

  • How do you reproduce the problem?

  • What behavior do you expect, and what behavior do you see?

  • When did the problem start occurring?

  • Are their circumstances in which the problem does not occur?

  • Is the problem permanent, intermittent, getting better, getting worse, or staying the same?

If you contact ForgeRock for help, include the following information with your request:

  • Description of the problem, including when the problem occurs and its impact on your operation.

  • The product version and build information.

  • Steps you took to reproduce the problem.

  • Relevant access and error logs, stack traces, and core dumps.

  • Description of the environment, including the following information:

    • Machine type

    • Operating system and version

    • Web server or container and version

    • Java version

    • Patches or other software that might affect the problem

Questions and answers

Detect the path of a resource loaded by classloader

Question: Why does the agent fails to initialize, with an error like this:

Servlet failed with an Exception: java.lang.NoSuchMethodError: com.sun.identity.shared.configuration.SystemPropertiesManager.getAsInt(Ljava/lang/String;I)I

Answer: An out-of-date version of the SystemPropertiesManager class is deployed in another jar, that did not have the getAsInt function, and the classloader chose the outdated class instead of the agent’s class.

Follow these steps to help locate jars containing outdated classes, by showing where these classes are loaded from:

  1. Add the property -Ddisplay.classpath.mode.enabled=true to the JVM properties in the container where the agent runs, and restart the container.

    JAVA_OPTS="$JAVA_OPTS -Ddisplay.classpath.mode.enabled=true"

  2. Access the URL of a protected resource, using the class name as a query parameter. The following example requests the path of the SystemPropertiesManager package:

    https://www.example.com/myapp/index.html?com.sun.identity.shared.configuration.SystemPropertiesManager

    If the agent finds the package, it displays the path. Otherwise, it displays an error.

  3. After troubleshooting, remove Ddisplay.classpath.mode.enabled=true from the JVM properties. While it is present, the agent returns the class path but performs no other function.

Cannot install over HTTPS

Question:

What should I do if I get an error like this when installing an agent with an HTTPS connection to AM:

AM server URL: https://am.example.com:8443/am

WARNING: Unable to connect to AM server URL....

If the AM server is TLS-enabled and the root CA certificate for the AM
server certificate has been not imported into the installer JVMs key store (see
installer-logs/debug/Agent.log for detailed exception), import the root
CA certificate and restart the installer; or continue installation without
verifying the AM server URL.

Answer:

The Java platform includes certificates from many certificate authorities (CAs). If, however, you run your own CA, or you use self-signed certificates for HTTPS on the web application container where you run AM, then the agentadmin command cannot trust the certificate presented during connection to AM, and so cannot complete installation correctly.

After setting up the web application container where you run AM to use HTTPS, get the certificate to trust in a certificate file. The certificate you want is that of the CA who signed the container certificate, or the certificate itself if the container certificate is self-signed.

Copy the certificate file to the system where you plan to install the Java agent. Import the certificate into a trust store that you will use during Java agent installation. If you import the certificate into the default trust store for the Java platform, then the agentadmin command can recognize it without additional configuration.

For information about export and import of self-signed certificates, refer to Configuring AM’s container for HTTPS of AM’s Installation guide.

Infinite redirection loops with stateless sessions

Question:

I have client-based (stateless) sessions configured in AM, and I am getting infinite redirection loops. In the debug.log file I can see messages similar to the following:

<timestamp> +0000 ERROR [c53...348]state identifier not present in authentication state
<timestamp> +0000 WARNING [c53...348]unable to verify pre-authentication cookie
<timestamp> +0000 WARNING [c53...348]convert_request_after_authn_post(): unable to retrieve pre-authentication request data
<timestamp> +0000 DEBUG [c53...348] exit status: forbidden (3), HTTP status: 403, subrequest 0

What is happening?

Answer:

This redirection loop happens because the client-based (stateless) session cookie is surpassing the maximum supported browser header size. Because the cookie is incomplete, AM cannot validate it.

To ensure the session cookie does not surpass the browser supported size, configure either signing and compression or encryption and compression. For more information, refer to AM’s Security guide.

Redirection URI error after upgrade

Question:

I have upgraded my agent and I see the following message in the agent log:

redirect_uri_mismatch. The redirection URI provided does not match a pre-registered value.

What should I do?

Answer:

Java Agent accept only requests sent to the URL specified by the Agent Root URL for CDSSO property. For example, http://agent.example.com:8080/.

As a security measure, agents prevent you from accessing the agent on URLs not defined in the Agent Root URL for CDSSO property. Add entries to this property when: