Verify Business User and Company after self-registering, a B2B Use Case

Some time ago, I published an blog note named Business User and Company Onboarding in ForgeRock Identity platform, a B2B Use Case where I explain how we to create user journeys in ForgeRock/Ping Identity platform for self-registering a business account and a company in the platform. This blog note is the continuity and propose how to verify the user account and how to validate the company.

The concept

Let’s briefly explore the various concepts we will implement here. In my previous blog note I already explained how I plan to validate the user account and the Company ownership. Below is an extract of my previous blog.

Validating the business user

To verify the authenticity of a user’s identity, we employ various mechanisms known as Know Your Customer (KYC). Identity Verification is a fascinating topic I may discuss in another blog note about Ping One Verify but for this one I’ll use a really classical one: email validation. I’ll send an email to the user with a temporary clickable link to confirm his account. With this I’m sure he is the owner of the email he used to register.
In a B2B scenario, validating the user through email verification may suffice, provided that there is a prior verification of the user’s identity by the company before generating a corporate email for them.

Checking Company ownership

To check the company ownership I’ll use a simple system that is already used by most of the SaaS companies: DNS entries checking. I’ll create a unique token for each company (stored in the object) and then ask the user to add a TXT DNS entry containing this token. If the user is allowed to modify the DNS entry for his company, then it means he is the owner of this domain — and thus the company.

We don’t want to setup a schedule task to check if the DNS entry has been updated. It’s no need to validate the Company object if none user is connecting to the platform so I decided to check the dns only when a user associated to this Company is registering or connecting. It means we will have to modify the onboarding and the login journeys.

How to in ForgeRock/Ping Identity Platform

Update the Register Org journey

When we create an Organization in the system, we want the user to add a new DNS entry to prove he is the owner of the domain. In the previous blog note we already generated a dns token an stored it in the Organization object. Now we want to display this token and ask the user to update his dns entry.

Firstly, create a script to display a dynamic message containing the DNS Token using a Configuration Provider node.

1. Select your realm (default is alpha), browse to Scripts>Auth Scripts and click on New Script to create a new one and choose a Configuration provider Node type,
2. Select the Next Generation Script Engine and click Next,
3. On the script creation page, name your script displayDnsToken,
4. In the Script field enter the following code and click on Save and Close.

Now, let’s update the Register Org journey to add a page to display the token to the user.

1. Browse to Journeys and click on RegisterOrg journey,
2. Add a Configuration Provider node, name it Display DNS Token, select “displayDnsToken” as Script and select Node Type equal “Message Node”. Link true, falseand Configuration failure to Success exit (Green circle icon).

Register Org journey updated to display the dns Token to update the register

Create a script library to check DNS entries

To check the DNS entries we will use DNS Over HTTP (DoH). The principle is simple: you request all the DNS entries using a REST Call (GEt or POST) and you receive the full DNS entries in JSON format. To get an idea of the result you can simply try this addresse https://dns.google/query?name=forgerock.com

DNS over HTTP ForgeRock.com entries

Example of a REST call from the command line: curl 'https://dns.google/resolve?name=forgerock.com&type=16'

DNS over HTTP — curl command

Note: There are many different companies that provides this service. In this blog note we’ll use the free service from Google.

With the October 31st 2023 version of the platform it’s now possible to create javascript libraries you can reuse in many different user journeys. This is explained here in the product documentation.

Let’s create a library to request the DNS entries of a specific Domain and check if the dnsToken has been updated in the DNS entries.

1. Select your realm (default is alpha), browse to Scripts>Auth Scripts and click on New Script to create a new one and choose a Library type,
2. Select the Next Generation Script Engine and click Next,
3. On the script creation page, name your script checkDomainLib,
4. In the Script field enter the following code and click on Save and Close.

Now that we created a script to check dns, let’s create another script to updates user login and user registration journeys.

Create a Script to check DNS token in login and register user journeys

Create a script to be used in Login and register user journey this script will use the previous library.

1. Select your realm (default is alpha), browse to Scripts>Auth Scripts and click on New Script to create a new one and choose Journey Decision Node type,
2. Select the Next Generation Script Engine and click Next,
3. On the script creation page, name your script checkDns,
4. In the Script field enter the following code and click on Save and Close.

Note: this script doesn’t check if the Organization is activated or not; it always requests the DNS. You can easily modify this script to check only if the Company has a status “inactive’.

Create a new login journey

Instead of modifying the default login journey, I prefer to create another one and update it. To create a user journey it is possible to duplicate an existing journey. We’ll do this to create this new login journey by duplicating the default Login user journey.

1. Browse to Journeys search for the journey Login, click on the “…” icon, and select Duplicate.
2. On this page, name the journey LoginB2B for Identity Object Alpha realms — Users.
3. Add an Inner Tree Evaluator node, name it Create Company Subtree, set Tree Name as “RegisterOrg”. Link True and False to Success exit (Green circle icon).
4. Add a Message Node, name it Create Company?, add a message: “Do you want to Create your Company ?”, a Positive answer: “Yes” and a Negative answer: “No”. Link true to Create Company Subtree node and link false to Success exit (Green circle icon).
5. Add a Scripted Decision node, name it CheckDns, select “checkDns” script, add true outcomes, link true to Success exit (Green circle icon),
6. Add an Identify Existing User node, name it getUser, set Identity Attribute equals to “userName”. Link True and False to CheckDns node.
7. Add a Query Filter Decision Node, name it Users company exists?, set Query filter as /memberOfOrgIDs pr and /memberOfOrgIDs/0 pr and leave the default value for Identity Attribute. Link true to GetUser node and link false to Create Company? node,
8. Finally, from the InnerTree Evaluator, link the Link true to Users company exists? node.

The following figure presents the LoginB2B journey as it should be.

LoginB2B user journey

Update the business user registration journey

Now Update your RegistrationB2B journey to add the mechanism to check if the DNS entry has been updated.

1. Browse to Journeys and click on RegistrationB2B journey,
2. Add a Scripted Decision node, name it CheckDns, select “checkDns” script, add true outcomes, link true to Success exit (Green circle icon),
3. Add an Identify Existing User node, name it getUser, set Identity Attribute equals to “userName”. Link True to CheckDns node and False to Failure exit (red circle icon),
4. Add a Configuration Provider node, name it Display DNS Token, select “displayDnsToken” as Script and select Node Type equal “Message Node”. Link true, falseand Configuration failure to Success exit (Green circle icon),
5. Finally, from the User company exists? node, link the Link true to getUser node and from the Create Company Subtree node, link true and false to getUser node.

You should have the following journey.

RegistrationB2B updated journey

And finally, add an email suspend node to send a validation email to the user. We use this mechanism here to validate the user is trully the owner of this email addresse.

1. Browse to Journeys and click on RegistrationB2B journey,
2. Add a Email Suspend node, name it EmailValidation, leave the default paramrters (you should have a default registration email template). Link the node exit to Create Object node, and link the Page Node exist node to EmailValidation node
3. Et voila ! You added a user validation to your registration tree.

Your new RegistrationB2B journey should look like the figure below.

RegistrationB2B updated journey with email validation

Demonstration

The gif below shows the dns check in action from the enduser and the admin point of view. Everything is done in background and the sttus is updated.

DNs Check when login Business user

Conclusion

This blog marks the culmination of my series on a B2B use case: facilitating the self-registration process for both individual business accounts and entire companies. Throughout this series, we’ve delved into the versatility of managing various user types and organizational structures within a seamless journey. Additionally, we explored the potential for integration with third-party APIs to verify DNS entries.

In an upcoming blog post, I will present the integration of our PingOne Verify service. This service offers a robust solution for verifying user identities, leveraging functionalities such as selfie verification and ID card validation. These features are seamlessly integrated into the user journey, all within the framework of PingOne Advanced Identity Cloud (formerly known as ForgeRock Identity Cloud).