Business User and Company Onboarding in ForgeRock Identity platform, a B2B Use Case

9 min readFeb 22, 2024

A few weeks ago, I encountered an atypical scenario in terms of identity management, but one that is quite common in SaaS applications for businesses.
How to register yourself and your company and prove that you’re legitimate and the real owner of that company? In this blog post, I’ll explain how to do this with ForgeRock Identity platform (now part of Ping Identity).

The Use Case

The use case is really simple: a company C offers online services to enterprises and would like to allow any customer to register an account using his company email and create it’s Company in the Platform (or link his account to the company if it already exists). All this using mechanism to prove the user is the real owner of the email and the company. the following diagram gives an overview of the expected use case.

The concept in ForgeRock

Let’s briefly explore the various concepts we will implement here.

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.

Associate users to Company

I’ll use a dynamic condition based on email domain name to automatically link users to the Company they belong.

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.
Every time a user associated to this company is login in I’ll check if the company has been validated, if not I’ll check on the fly the DNS entry to update the status of the Company.

A Simple Data Model

In ForgeRock platform you can manage Users/Identities, Roles, Assignments and Organisations. In this post, I’ll use Users objects of course to manage Business users but I’ll also use Organisations objects to manage the Companies. After the User and his Company are onboarded we’ll have in ForgeRock platform a Users objects linked to an Organisation objects.
In addition, we’ll extend the Organisation Object schema with 3 attributes:

condition: contains a rule to automatically associate users to the company,
domain: contains the domain name of the company,
dnsToken: contains the token used to check company ownership.

Now, let’s configure it in ForgeRock Identity Platform.

Update the Data Model

In the Identity Platform it’s possible to extend your data model as explained in this page. You can:

Add new managed object types.
Specify default values for object properties
Derive object property values from other object property values, known as virtual properties.
Define custom relationships between managed objects.

Follow these steps to add 3 new attributes to the Organization Object Schema.

Add condition attribute

To extend the data model here, I decided to do it with the REST API instead of using the UI. To do so, the only prerequisite is to have an admin account. It’s the account we’ll use for the REST API calls. To create a service account in ForgeRock Identity Cloud (aka PingOne Advance Identity Cloud — P1AIC), just follow the online documentation “ Service accounts”.

From your shell, use this page to Authenticate to Identity Cloud REST API with access token,
Get the managed object configuration in a json file with this REST call curl --request GET 'https://<YOUR TENANT>/openidm/config/managed' --header "Authorization: Bearer ${AT}" > managed-$(($(date -u +%s))).json, where <YOUR TENANT> is equal to your platform server, AT is equal to the access token you obtained during step 1 and managed-<date>.json is the json configuration file and <date> is equal to the date of the day,
Copy the managed-<date>.json into a new one cp managed-<date>.json managed.json
In managed.json file, locate "name": "alpha_organization" object and in "schema">"order" attribute table, add the value"condition",
In managed.json file, locate "name": "alpha_organization" object and in "schema">"properties" attribute, add this json object "condition":{"title":"Condition","isConditional":true,"type":"string","viewable":false,"searchable":false,"userEditable":true,"description":"A conditional filter for this org","isVirtual":false},
In managed.json file, locate "name": "alpha_organization" object and in "schema">"properties">"members">"items">”resourceCollection” attribute table, add the value"conditionalAssociation": true,
In managed.json file, locate "name": "alpha_user" object and in "schema">"properties">"memberOfOrg">"items">”resourceCollection” attribute table, add the value"conditionalAssociationField": "condition",
Now, update the configuration with this REST call curl --request PUT 'https://<YOUR TENANT>/openidm/config/managed' --header "Authorization: Bearer ${AT}" --header “Content-Type: application/json” --data managed.json, where <YOUR TENANT> is equal to your platform server, AT is equal to the access token you obtained during step 1 and managed.json is the json configuration file
That’s it, your data model has been updated with a new conditional attribute !

Now if you connect the Identity Platform UI, you browse to the Identities>Manage section and you edit an Organization, you’ll see a new Tab named “Settings”. This is where you’ll be able to define a rule to automatically assign an Organization to a user.

Add domain, dnsToken, and status attributes

This time, we’ll do this using the native Identity Management console.

With your browser, connect to your platform UI https://<YOUR TENANT>/platform (where <YOUR TENANT> is equal to your platform server) as an administrator, and browse to Natives Consoles > Identity Management Menu. It should open a new window.
In this new window, browse to Configure > Managed Objects. On this page click on “Alpha_organization”.
Click on “Add a Property”, name this property domain, with a label Domain and a type String, and click “Save”.
Click on “Add a Property”, name this property dnsToken, with a label DNS Token and a type String, and click “Save”.
Click on “Add a Property”, name this property status, with a label Status and a type String, and click “Save”.
That’s it your data model has been updated.

Now if you connect the Identity Platform UI, you browse to the Identities>Manage section and you edit an Organization, you’ll see 2 new attributes in the interface ready to be set for any organization.

Organization domain, dns token & status attributes

Configure user journeys

Create the “register company” user journey

First of all we will create the scripts that we’ll use in the tree.

Connect to your ForgeRock Identity platform console (https://<YOUR-TENANT>/platform/) and follow theses steps.

Create a script to generate a DNS Token and set a rule to dynamically assign the Organization to a user based on it’s mail domain.

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

Now that we pre-created the script, let’s create the journey.

When you create a journey you have to specify the Identity Object on which the journey will operate. For years I was wondering when would I have to operate on another object than user. With this use case, it is the exact situation where I need this feature. Let’s create this journey.

Browse to Journeys and click on New Journey to create a new one called RegisterOrg for Identity Object Alpha realms — Organization,
Add a Create Object node, name it Create Company, set Identity Resources as “managed/alpha_organization”. Link Created to Success exit (Green circle icon) and Failed to Failure exit (red circle icon),
Add a Scripted Decision node, name it CreateDnsToken, select createDnsToken script, add true outcomes, link true to Create Company node,
Add a Required Attributes Present Node, set Identity Resources as “managed/alpha_organization”. Link true to CreateDnsToken node and link false to Failure exit (red circle icon),
Add a Attribute Collector node, define “name” “description” and “domain” as Attributes to collect. Link the start of the journey to this node and the outcome to Required Attributes Present node. Et voila !

The following figure presents the journey in ForgeRock Intelligent Authentication web designer.

With this journey it’s possible to create an Organization from a user journey and it automatically create a dynamic rule to automatically assign users to this company based on their mail domain. To automatically modify this dynamic rule in case of the domain attribute of the company change, we will use Events hooks. Theses hooks are triggered based on Object events and can execute scripts as explained in this documentation page.

Configure onUpdate Event Hook

Let’s see how to create a Event Hook when an Organization is updated (=event onUpdate):

Browse to Event Hooks and click on New Event Hook,
Name it “SetConditionOnDomainUpdate”,
Select Object Name “Alpha realm — Organization”, event “is updated (onUpdate)”,
In the Script field enter the following code and click on Save.

The following figure shows how it should look like.

Note: You can create the same event hook for onCreate Event if you plan to create Companies manually without using the journey.

Create the “register business user” user journey

To create a user journey it is possible to duplicate an existing journey. Doing this will save you some time and spare you from starting from scratch. We’ll do this to create this new onboarding journey by duplicating the default Register user journey.

Browse to Journeys search for the journey Registration, click on the “…” icon, and select Duplicate.
On this page, name the journey RegistrationB2B for Identity Object Alpha realms —Users.
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).
Note: we link both exists to success but it could be interesting to notify the user in case of an error while creating the Org. To do that you may link theFalse outcome to a Message node.
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).
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 Success exit (Green circle icon) and link false to Create Company? node.

The following figure presents the journey in the Platform Intelligent Authentication web designer.

Demonstration

The video below shows the result in action from the user perspective.

The next screenshot shows the Business user created in the Identity Platform and linked to the Organization we just created.

In the next figure you can see the Google company created in the Identity Platform with the domain mail and the dnsToken.

Conclusion

In this blog post, we’ve seen how to configure ForgeRock Identity Platform for a B2B use case where the user can register for an account and also create it’s company in the System. For now, the user and the company are not verified, we’ll see it in another blog note.