Mail Change with Verification in IDM 6.5

In this scenario, a user can change his or her own mail address. Since the mail address usually fulfills a special task, we want to get a confirmation from the user before changing the mail to only allow checked changes. This is achieved by a validation link in the mail to the new address. Only when the validation has taken place, the new mail address is changed to the user profile and the internal validation data is deleted.


Forgerock IDM 6.5 offers a range of pre-built self-service modules. This use case is not implemented by default. This section shows how easy it is to implement customer-related application cases.

Some configurations have been changed to show this. The prerequisites below are intended to illustrate this.

User Flow

User Flow


  • the sample code under samples/sync-with-csv was used as basis
  • created mailHelper.js file under ./script
  • emailTemplate-verifyChange.json file in ./conf created
  • new object configuration in managed.json under ./conf
  • custom rest endpoint mailvalidation under ./conf and ./script
  • Mail configuration to send mails ./conf (smtp config)
  • access.js under ./script to call the custom rest endpoint (for mail validation)

Details of the Flow

1. User changes his mail address in user dashboard:

Users log in at http://localhost:8080/#/profile and change their email address. A script “onUpdate” is triggered for the Managed User Object.

onUpdate script (this is always executed if a user profile changes):

require('onUpdateUser').preserveLastSync(object, oldObject, request);require('mailHelper').checkChange(context, 'mail', object, oldObject);

onUpdate is called by mailHelper.js (.script/) and creates the following in the user:

"verificationData": {
                "mail": {
                    "code": 72594,
                    "value": ""

NOTE: The old mail address in the mail attribute is not changed. Rather, the new mail address with validation code can be found under verificationData.mail.

Mail will be sent to the new mail address. The mail contains a URL that the user can click on to verify the new mail address.

Code Snipplet for the sending of mail:

Here a mail template is used instead of hardcoding it into the function. A JSON file in the Conf directory of the IDM project is sufficient for this. Just save the JSON as emailTemplate-myTemplateName.json.

var emailConfig ="config/"),
    Handlebars = require('lib/handlebars'),
    emailTemplate ="config/emailTemplate/verifyChange");

// revert the change to the attribute, pending verification
object[attribute] = oldObject[attribute];

// copied from onCreateUser.emailUser()
var email,
    locale = emailTemplate.defaultLocale;

email =  {
    "from": emailTemplate.from || emailConfig.from,
    "to": object.verificationData[attribute].value,
    "subject": emailTemplate.subject[locale],
    "type": "text/html"

template = Handlebars.compile(emailTemplate.message[locale]);

email.body = template({
    "object": object,
    "verification": object.verificationData[attribute]

// do NOT wait for completion, so that this call will succeed even if email fails to send
openidm.action("external/email", "send", email, { waitForCompletion: false });

Validation can be easily tested using a Curl Command or Postman:

2. User receives a mail with the Validation Link

endpoint/mailvalidation Beispiel:


The call compares the parameters with the validation data stored in the user profile (userid: userid=bjensen), if these are correct the validation data is deleted and the mail attribute is set to the new mail address.

Thanks to

Jake for initial scripts (especialliy to call the mail template!!!)

The complete IDM project code is publicly available on stash.

Use of this code requires a commercial software license with ForgeRock AS. or with one of its affiliates. All use shall be exclusively subject to such license between the licensee and ForgeRock AS.

Copyright 2014-2017 ForgeRock AS. All Rights Reserved

Forgerock Copyright

One-Way Sync With CSV Sample

This sample demonstrates reconciliation between a CSV file and the managed/user repository. For documentation relating to this sample, see Source Code of this example is under

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.