Child pages
  • Custom Endpoint Email Verification Example
Skip to end of metadata
Go to start of metadata

Use Case:
When user performs self-registration, the registration system should perform a check on their registered email address, to make sure it is live and valid before provisioning to other target systems. This will be done by sending out a verification link to the user, which contains a unique verification code that the user enters to confirm their email address is live. Once confirmed, user is classified as verified, and can be provisioned to appropriate systems.

Enable Self-registration
Within conf/ui-configuration.json file, set "selfRegistration" : true, within the configuration object. Refresh the UI to see the register account link.

Setup External Email Server
We'll need an external email server so we can send out the verification emails. Edit the conf/ file with your email server details.

Set On-Create Default Values
We need to set some attribute values at creation time, in order to manage the verification process. Via the conf/managed.json file, the default onCreate action, calls bin/defaults/script/ui/onCreate-user-set-default-fields.js. Edit this file to add a user.verified=false attribute and also a user.verificationCode attribute. The value of the user.verificationCode should be a random number/string of 6-8 characters. This can be generated using a piece of Javascript separate. At the end of the onCreate defaults, we need to send out an email to the registered email address with the verification code and a link to click to verify it.


Create Custom Endpoint To Handle Verification Response
The verification URL we sent out in the email, points to a custom endpoint. We need to build out the endpoint to handle the response and update the user to acknowledge they're verified.

Create a file called conf/endpoint-verifyEmail.json with the following settings:

                "context" : "endpoint/verifyEmail",
                "type" : "text/javascript",
                "file" : "script/verifyEmail.js"

Create the script/verifyEmail.js to handle the verification. This needs to take the username and verification code given as parameters in the URL, check the code matches and update the user appropriately.

This basically confirms the code submitted matches to that of the found user record. If so, the attribute verified=false is patched to verified=true.

NOTE – this is an example endpoint as a proof of concept. No parameter or request checking is being done here and could be open to SQL injection and other attacks.  To really implement this fully, a custom user interface component would capture the username and verification code via a form, which, via javascript could forward an asynchronous call to the custom endpoint for example.

The verified=true attribute can then be leveraged in the appropriate conf/sync.json mapping, for like validSource checking, or making accounts active/inactive on target systems, if already provisioned.

Allow Access To Your Endpoint
OpenIDM doesn't allow fully un-authenticated user access to any endpoints. OpenIDM however, does come with an anonymous user that can be used for self-registration and also access to our custom endpoint. Edit the script/access.js file to add in an authorization entry for the custom endpoint, with the openidm-reg role (that gives anonymous access) able to access the endpoint.

//Used to verify email addresses so public
                "pattern" : "endpoint/verifyEmail",
                "roles" : "openidm-reg*",
                "methods" : "read, query",
                "actions" : "*",

To access the endpoint during a proof of concept or test, simply use curl or a browser based REST client, adding in a header with the anonymous username and anonymous password.

Code available here on Github

  • No labels


  1. Unknown User (jjamieson1)

    Thank you for the well written example.  One question though.  The REST client can use the web service like you stated, by adding the username and password (anonymous, anonymous).  However when a user clicks the link emailed to them, this username, password will not be in their header and the endpoint access is denied.  Is their a way to allow unauthenticated users access to a custom endpoint?

    1. So basically, the above is just to show the endpoint setup.  In production you'd probably need a web UI to consume the response from the end user (be that a form to enter the verification code, or a URL) and have that UI component just pass the details across the custom endpoint with the anon credentials.  You're right the email link wont construct the necessary header and OpenIDM requires a user to be authenticated even if just with anon:anon.

  2. Unknown User (f3nrico)

    Nice tutorial.

    With openidm 3.1.0 this however dosn't work, i made these corrections:

    submittedVerificationCode = request.additionalParameters['verificationCode'];

    openidm.action("external/email", "send", params);

    openidm.patch("managed/user/" + user._id, null, [{"operation" : "replace", "field" : "/verified", "value": "true"}]);