Troubleshooting
ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to help you set up and maintain your deployments. For information about getting support, see 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
Cannot Install Over HTTPs
Question:
I am trying to install a Java agent, connecting to AM over HTTPS, and seeing the following error:
AM server URL: https://openam.example.com:8443/openam WARNING: Unable to connect to OpenAM server URL. Please specify the correct OpenAM server URL by hitting the Back button (<) or if the OpenAM server URL is not started and you want to start it later, please proceed with the installation. If OpenAM server is SSL enabled and the root CA certificate for the OpenAM server certificate has been not imported into 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 OpenAM server URL.
What should I do?
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.
Export and import of self-signed certificates is demonstrated in Configuring AM’s Container for HTTPS of AM’s Installation Guide.
Cannot Install WebSphere Java agent on Linux
Question:
I am trying to install the WebSphere Java agent on Linux. The system has IBM
Java. When I run agentadmin --install
, the script fails to encrypt
the password from the password file, ending with this message:
ERROR: An unknown error has occurred (null). Please try again.
What should I do?
Answer:
Edit agentadmin
to use IBMJCE, and then try again. For information,
see Install With IBM Java.
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, see 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:
-
Configuring Alternative Agent Protocol to access the agent through different protocols. For example,
http://agent.example.com/
andhttps://agent.example.com/
. -
Configuring Alternative Agent Host Name to access the agent through different virtual host names. For example,
http://agent.example.com/
andhttp://internal.example.com/
. -
Configuring Alternative Agent Port Number to access the agent through different ports. For example,
http://agent.example.com/
andhttp://agent.example.com:8080/
.
File Not Found Errors After WebSphere Installation
Question:
After installing a Java Agent on WebSphere, accessing a URL for a folder in a
protected web application such as http://openam.example.com:9080/test/
results in
Error 404: SRVE0190E: File not found: {0}
, and redirection fails. What should
I do to work around this problem?
Answer:
Perform the following steps to work around the problem, by setting the WebSphere
custom property com.ibm.ws.webcontainer.invokeFiltersCompatibility=true
:
-
In the WebSphere administrative console, browse to Servers > Server Types, and then click WebSphere application servers.
-
Click the server to apply the custom property to.
-
Navigate to Configuration > Container settings > Web Container Settings > Web container.
-
Under Configuration > Additional Properties, click Custom Properties.
-
In the Custom Properties page, click New.
-
In the settings page, enter the Name
com.ibm.ws.webcontainer.invokeFiltersCompatibility
and Valuetrue
for the custom property.Some properties are case-sensitive.
-
Click Apply or OK as applicable.
-
Click Save in the Message box that appears.
-
Restart the server for the custom property to take effect.
For more information, see the IBM documentation, Setting webcontainer custom properties.