ForgeRock Self-Service Custom Stage IDM 5.x


A while ago I blogged an article describing how to add custom stages to the ForgeRock IDM self-service config. At the time I used the sample custom stage available from the ForgeRock Commons Self-Service code base. I left it as a task for the reader to build their own stage! However, I recently had cause to build a custom stage for a proof of concept I was working on.

It’s for IDM v5 and I’ve detailed the steps here.

Business Logic

The requirement for the stage was to validate that a registering user had ownership of the provided phone number. The phone number could be either a mobile or a landline. The approach taken was to use Twilio (a 3rd party) to send out either an SMS to a mobile, or text-to-speech to a landline. The content of the message is a code based on HOTP.

Get the code for the module

Building the module

Follow the instructions in

After deploying the .jar file you must restart IDM for the bundle to be correctly recognised.

The module is targeted for IDMv5. It uses the maven repositories to get the binary dependencies.

See this article in order to access the ForgeRock ‘private-releases’ maven repo:
How do I access the ForgeRock protected Maven repositories?

It also uses appropriate pom.xml directives to ensure the final .jar file is packaged as an OSGi bundle so that it can be dropped into IDM

Technical details

The code consists of a few files. The first two in this list a the key files for any stage. They implement the necessary interfaces for a stage. The remaining files are the specific business logic for this stage.

  • This class manages reading the configuration data from the configuration file. It simply represents each configuration item for the stage as properties of the class.
  • This is main orchestration file for the stage. It copes with both registration and password reset scenarios. It manages the ‘state’ of the flow within this stage and generates the appropriate callbacks to user, but relies on the other classes to do the real code management work. If you want to learn about the way a ‘stage’ works then this is file to consider in detail.
  • This is taken from the OATH Initiative work and is unchanged by me. It is a java class to generate a code based on the HOTP algorithm.
  • This class manages the process of sending the code. It generates the code then decides whether to send it using SMS or TTS. (In the UK, all mobile phone numbers start 07… so it’s very simple logic for my purpose!) This class also provides a method to validate the code entered by the user.
  • The class provides the utility functions that interact directly with the Twilio APIs for sending either an SMS or TTS


There are also two sample config files for registration and password reset. You should include the JSON section relating to this class in your self-service configuration files for IDM.
For example:

“class” : “org.forgerock.selfservice.twilio.TwilioStageConfig”,
“codeValidityDuration” : “6000”,
“codeLength” : “5”,
“controlUrl” : “”,
“fromPhone” : “+441412803033”,
“accountSid” : “<Enter accountSid>”,
“tokenId” : “<Enter tokenId>”,
“telephoneField” : “telephoneNumber”,
“skipSend” : false

Most configuration items should be self explanatory. However, the ‘skipSend’ option is worthy of special note. This, when true, will cause the stage to avoid calling the Twilio APIs and instead return the code as part of the callback data. This means that if you’re using the OOTB UI then the ‘placeholder’ HTML attribute of the input box will tell you the code to enter. This is really useful for testing this stage if you don’t have access to a Twilio account as this also ignores the Twilio account specific configuration items.

Of course, now you need to deploy it as per my previous article!