Friday, 23 September 2016

A Beginners Guide to OpenIDM - Part 5 - User Registration

Last time we configured mappings to create user objects in OpenIDM from a CSV file. This is commonly something you might do when populating a new identity system for the first time with your existing users, but what about getting new users into the system?

This blog we will take a look at configuring OpenIDM's user self registration functionality and how we can perform some post processing on new users.

Note: As many of you will be aware OpenIDM 4.5 has recently been released, for now I am going to continue using OpenIDM 4 for this blog but everything we talk about here is still applicable to 4.5, albeit with minor differences. I will likely move to OpenIDM 4.5 (or 5 even) when the beginners series is concluded.

This blog continues my OpenIDM Beginners series, catch up with the links below:

A Beginners Guide to OpenIDM - Part 5 - User Registration
A Beginners Guide to OpenIDM - Part 6 - Provisioning to Active Directory

User Registration

To turn on User Registration in OpenIDM, first log in as an administrator. Then navigate to Configure, then User Registration.

 You will see the User Registration configuration screen:

Now before we turn it on, log out and take a look at the OpenIDM user login screen:

Just try to remember what it looks like right now, as it will change in a moment.

By default, User Registration is disabled. Lets enable it now. Click the "Enable User Registration" slider.

You can see that we have a number of Registration Steps. These can be turned on and off as you require, they can also be re-ordered by dragging and dropping.

Lets briefly talk about what each of these steps involves:

  • reCAPTCHA for Registration: Google's "I am not a robot" dialog. To prevent automated bots registering.
  • Email Validation: User is sent an email, they must click a link in the email to progress registration. Verifying that they do indeed have access to the email account.
  • User Details: Simply allows you to modify the attribute on the user object associated with email address. By default this is mail but you might want to change it based on your managed user schema if you have made changes.
  • KBA Stage: Whether or not to enforce the use of Knowledge Based Authentication i.e. challenge questions and answers.
  • Registration Form: Here you can change the Identity Service URL to another managed object.
Note that you cannot configure everything in the UI, but we will shortly take a close look at how you can do that for Email Validation and KBA Stage if required.

So lets make sure that we have turned everything on in the as in the image above, except for reCAPTCHA. There is no save button. Toggling the sliders is sufficient here.

Now log out again, and take another look at the user login screen:

You should see we now have a link to Register. You can take a look but this won't really work yet as we need to configure the steps, mainly Email Validation. So lets do that now.

Configuring Email Validation

We need to configure Email Validation and for this we are going to need an email server. If you have an email server, great. If not I suggest downloading something like

Navigate to Configure, then System Preferences.

Select the Email tab.

Toggle the Enable Email slider, then Use SMTP Authentication.

Enter the host, port and credentials for your email server.

Then press Save.

Testing Registration

Logout of OpenIDM, navigate to the user login page: and select the Register link again.

Enter a test email address and press SEND.

All being well you should receive an email:

If you click the link, you will continue the registration process in OpenIDM.

Press Save, then you can complete your KBA questions:

When that is done, press Save for the final time and you should see that...

Registration is complete, if you Return to Login Page you should be able to log in with your new user ( by default this is the username we set on the 2nd page, not the email address ).

Customising Registration

As with everything ForgeRock every step of the Registration process can be customised, and you can use our REST API's if you want to build a completely customised experience.

However there are two customisations which are frequently performed, let's take a quick look at them now.

Customising the Registration Email

This can be easily achieved through the UI, if you return to Configure, then User Registration and edit the Email Validation step.

If you prefer you can also edit this directly via <openidm>/conf/selfservice-registration.json

Customising KBA Challenge Questions

If you want to edit KBA questions you need to do this directly by editing <openidm>/conf/selfservice.kba.json

Friday, 16 September 2016

Debugging OpenAM and OpenIDM

My background is 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.


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.


This is where you find the debug logs. Generally very detailed logs for all the different components of OpenAM.


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:

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.


Again, there are actually two places to check when debugging OpenIDM:


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:


There is a helpful guide as to how do that here:

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.

Check the source code

Perhaps the biggest differentiator with ForgeRock. You can go and look at the source code:

In the old legacy world I would frequently decompile and sift through code to resolve issues. Those days are well and truly over.