Debugging OpenAM and OpenIDM

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.

This blog post was first published @ http://identity-implementation.blogspot.no/, included here with permission from the author.

A Quick & Easy Way to Create Test Users in OpenAM

More often then not we need ways to create test users and this isn’t something that we want to spend large amounts of time doing. Helpfully OpenAM comes bundled with a script which can quickly let you do this.

There is a script named make-ldif that can be found here: openam/opends/bin

This script generates an ldif file that contains a set of test users which randomly generate names, email addresses and other attributes. An example of this output is below:

 dn: uid=user.41,ou=People,dc=example,dc=com  
 objectClass: top  
 objectClass: person  
 objectClass: organizationalperson  
 objectClass: inetorgperson  
 givenName: Addie  
 sn: Achille  
 cn: Addie Achille  
 initials: AJA  
 employeeNumber: 41  
 uid: user.41  
 mail: user.41@example.com  
 userPassword: password  
 telephoneNumber: +1 892 829 0033  
 homePhone: +1 307 295 8896  
 pager: +1 397 006 1503  
 mobile: +1 168 140 0201  
 street: 86587 Hillcrest Street  
 l: Santa Fe  
 st: NJ  
 postalCode: 76090  
 postalAddress: Addie Achille$86587 Hillcrest Street$Santa Fe, NJ 76090  
 description: This is the description for Addie Achille.  

To run the script, you need to configure the example.template file to match your environment and user attributes.

 define suffix=dc=example,dc=com  
 define maildomain=example.com  
 define numusers=10001  
 branch: [suffix]  
 branch: ou=People,[suffix]  
 subordinateTemplate: person:[numusers]  
 template: person  
 rdnAttr: uid  
 objectClass: top  
 objectClass: person  
 objectClass: organizationalPerson  
 objectClass: inetOrgPerson  
 givenName: <first>  
 sn: <last>  
 cn: {givenName} {sn}  
 initials: {givenName:1}<random:chars:ABCDEFGHIJKLMNOPQRSTUVWXYZ:1>{sn:1}  
 employeeNumber: <sequential:0>  
 uid: user.{employeeNumber}  
 mail: {uid}@[maildomain]  
 userPassword: password  
 telephoneNumber: <random:telephone>  
 homePhone: <random:telephone>  
 pager: <random:telephone>  
 mobile: <random:telephone>  
 street: <random:numeric:5> <file:streets> Street  
 l: <file:cities>  
 st: <file:states>  
 postalCode: <random:numeric:5>  
 postalAddress: {cn}${street}${l}, {st} {postalCode}  
 description: This is the description for {cn}.  

The key attributes to change are:

define suffix=dc=example,dc=com  
define maildomain=example.com  
define numusers=10001  

Set the suffix and maildomain to match the installation of your OpenAM instance.
Set numusers to the number of test users you want to generate. I usually use about 500.

You will also need to add any attributes that you need users in the schema to have by default.

To save time, I have attached an example.template that will work perfectly with a clean installation of OpenAM that has the default out of the box domain suffix and attribute schema. Download it from here.

Once you have an example.template. You can run the make-ldif script using the command below, users.ldif is the desired output file:

 ./make-ldif -t ../config/MakeLDIF/example.template -o /usr/local/tools/users.ldif  

Finally, you can use the ldapadd tool to process users.ldif and create the users:

 ldapadd -h localhost -p 50389 -D "cn=Directory Manager" -w cangetinam -f /usr/local/tools/users.ldif -c  

The ldapadd tool will connect to the embedded DJ directory, ensure you update the host (-h), port (-p), bindDN (-D) and password (-w) to match your installation.

This should result with an OpenAM instance fully populated with users.

 

This blog post was first published @ http://identity-implementation.blogspot.no/, included here with permission from the author.