My background is the what I call the world of legacy identity, as such it took me a little while to get used to the world of ForgeRock, REST API’s and the like.
If you come from that world you may find debugging implementation issues with ForgeRock is a little different so I wanted to write up a short guide to share what I have learned.
Have you checked the logs?
Some things never change and your first port of call to debug any issues should be the log files.
OpenAM
There are actually two places to check when debugging OpenAM:
Note: <openam_install_dir> is the directory in which OpenAM was installed, not the web container.
<openam_install_dir>openam/debug
This is where you find the debug logs. Generally very detailed logs for all the different components of OpenAM.
<openam_install_dir>openam/log
This is where you find access and error logs. Detailing access requests and the result of those requests.
For example, if we look at access.csv:
You can see the result of my last login as amadmin.
Configuring log levels
If you don’t see anything, you may need to change the logging configuration.
Navigate to: http://localhost.localdomain.com:18080/openam/Debug.jsp
This interface is fairly straight forward
In the above example I have set the policy component to Message level.
Just hit confirm and the change will be made immediately without a restart required.
OpenIDM
Again, there are actually two places to check when debugging OpenIDM:
<openidm_install_dir>openidm/logs
The main OpenIDM log files can be found here. OpenIDM used JDK logging and the configuration file can be found here if you need to make changes to logging levels:
<openidm_install_dir>openidm/conf/logging.properties
There is a helpful guide as to how do that here: http://www.javapractices.com/topic/TopicAction.do?Id=143
So far that is all fairly standard, however if you do not find anything in the logs then you may want to examine the REST services.
Debugging REST services
As I have said a few times on his blog, the ForgeRock platform is completely underpinned by REST services.
The User Interfaces for OpenAM and OpenIDM both make extensive use of REST service calls in their functioning.
When debugging issues, especially anything that results in an error visible in the UI. You should take a look at the requests and responses.
I use FireFox Developer Tools to do this but I know there are equivalents for other browsers.
It’s as simple as turning on Developer Tools and examining the network requests whilst using OpenAM and OpenIDM.
So lets try making a new authentication chain in OpenAM.
What we need to find is the POST request for the creation of the chain. If you browse up and down the list you should find it pretty quickly. On the right you can see the Headers in the request, the parameters and importantly the response code:
And the response:
So let’s see what that looks like when we have an error:
Generally you will see something like the above, and if you check the actual response, you should see a more detailed message that can help you debug the issue.
Comments are closed.
Something that you may not have noticed is that every OpenAM debug output statement contains a TransactionId. This transaction ID is a unique identifier that you can use correlate all debug and audit output relating to a given HTTP request.
Also, if you’re looking at debugging across multiple OpenAM instances / a platform deployment, you may find it useful to enable propagation of the transaction ID: https://forgerock.org/openam/doc/bootstrap/maintenance-guide/index.html#configuring-trusttransactionheader-system-property