One way to prepare a set of Neuro-Access accounts for a predefined set of users, is to pre-create them using script and then generate onboarding codes that can be sent to the users. Once they receive their corresponding code, they can download the app, scan the code, and connect directly to the predefined account. This method allows you to create accounts on a predefined Neuron for a known set of users, without having to create API keys, and minimizing the risk of the users creating accounts on other neurons. It also allows you to predefine the account names.
To try the following tutorial, you need access to the script prompt on your neuron. The script prompt is available from the administrative page via this option:
Script Prompt from Admin portal
Creating the account
The main module of the XMPP broker, hosting the accounts, is Waher.Service.IoTBroker.XmppServerModule, or XmppServerModule for short. It has a property called PersistenceLayer that acts as an interface to the database for the XMPP server. This interface has a method called CreateAccount that allows us to create accounts. This method performs necessary checks to ensure the name is not occupied elsewhere, to protect integrity. Typing its fully qualified name into the prompt allows us to find its arguments:
CreateAccount method arguments
Note: Finding the names of the types, properties and methods is a combination of using the Namespaces & Types option from the administrative portal, and/or using the script prompt together with the methods and properties functions. You can also use the Neuron Documentation with its DoxyGen code documentation site where you can search for classes and other relevant names.
We are now ready to create accounts. We will generate account names that are GUIDs, using the NewGuid() script function. Each account will receive a random password with sufficient entropy, generated using the RandomPassword() script function. We will not use an API Key (leaving it empty), making the account behave as a manually created account. We will not assign e-mail adddresses or phone numbers to the accounts either. To ensure the account object has a proper remote endpoint associated with its creation, we will use the Request.RemoteEndPoint value, which will contain the remote endpoint of the person executing the script function via the script prompt. (If executing the script via some other interface, you might have to change this reference to something else.) The result of calling the CreateAccount method, is a KeyValuePair<IAccount,string[]> result, where the Key portion contains the new account, if created (or null if not), and the Value portion any alternative name suggestions in case the account could not be created.
Note: You can call properties(Account) to review the properties of the account. You can also see that access to the generated password is protected to reduce the risk of unauthorized access to the account.
Note 2: If you want, you can create a separate API key, and reference it when you create the account. This way, you can separate the accounts from other manually created accounts. You can also control the amount of accounts that can be created.
Creating an onboarding code
Next step is to create an onboarding code. This is done in cooperation with the onboarding neuron configured for the neuron on which the account was created. The onboarding code is a URI with the obinfo: URI scheme, that references the onboarding neuron, and contains a key and a secret. The onboarding neuron on the other hand receives an encrypted BLOB containg the information necessary to access the account. This information can only be decrypted using the secret key available in the onboarding code. Furthermore, the onboarding code can only be used once. You can also define a point in time when the code expires, if it has not been used.
Note: Since the code can only be used once, it is important to transfer the code in a way where it cannot be previewed by mistake. Previewing it will result in the code automatically expiring.
To create the code, we will call the GetOnboardingUrl method on the Account object. It takes one argument: The point in time when the code will expire if not used before. In the following example, we create a code that will be valid for three days:
Code:=Account.GetOnboardingUrl(Now.AddDays(3));
The Code will contain a string representing the onboarding URI. It will be of the form:
The Onboarding URI contains four parts, delimited by colons (:):
The obinfo URI scheme identifying the URI as an onboarding URI.
The onboarding neuron that contains the encrypted BLOB (but not the key).
The identifier of the encrypted BLOB.
The secret key necessary to decrypt the BLOB.
Creating an onboarding QR Code
The Neuron has a QR Code API that permits you to create QR codes for the onboarding URIs generated. The procedure is simple: A URL is generated pointing to the /QR resource on the neuron. After the resource name you add the contents you want to encode into the URI, prefixed by a /. The contents must be URL encoded. After the contents, you can add query parameters controlling how the QR code should be generated. This includes controlling the quality of the image, resolution and colors. Displaying a QR code on screen, or in an email requires less resolution, that including the image in print, for instance. A QR code for light mode displays (or white paper) should look different from QR codes for dark mode displays, for instance.
In the following example, we use the Waher.IoTGateway.Gateway.GetUrl(LocalResource) method to generate an absolute URL to an image containing a 400x400 pixel QR code encoding the onboarding URI just created. It uses a quality setting of 2, meaning 2x2 points are evaluated for every pixel generated, creating an anti-aliasing effect to create smoother edges.
The QR Code API documents parameters that can be used to control the colors used when generating the QR code. By appending &fg=white&bg=black&c=c0ffc0 to the URL, for instance, a QR code for dark-mode can be generated instead, as an example:
QR code of onboarding URI - Dark Mode
If higher resolution images are required, you can increase the w (width), h (height) and q (quality) settings. For example, an 800x800 image with 3x3 points per pixel quality would look like:
QR code of onboarding URI - Print
Batch creation of accounts
We are now ready to create script for the batch creation of accounts, and generate QR codes that can be distributed separately, for each account created. We will use the preview() function to display current progress in the prompt (and the batch procedure may require some time to execute, depending on the number of accounts and QR codes to create), the Get() function to retrieve the image from the generated QR Code URLs, and the SaveFile() function to save the QR codes generated, and the results of the batch procedure into a single JSON file. We will use the Waher.IoTGateway.Gateway.AppDataFolder property to save files in a location that is easily accessible, and where the Neuron has write-access. We will create a subfolder called Batch for the generated files. Finally, we generate an XML document with the same information, and store it as an XML file also. At the end we have a set of onboarding QR code image files, a JSON file with an index of all accounts created, and a similar XML file with the same information. We create the following batch account-creation function:
CreateAccounts([N]):=
(
Created:=NowUtc;
Accounts:=
{
"NrAccounts":N,
"Created":Created
};
Records:=[];
AccountNr:=1;
BatchFolder:=Waher.IoTGateway.Gateway.AppDataFolder+"Batch";
if !System.IO.Directory.Exists(BatchFolder) then
System.IO.Directory.CreateDirectory(BatchFolder);
while AccountNr<=N do
(
AccountNrStr:=Str(AccountNr);
preview("Creating account "+Str(AccountNrStr)+"...");
do
(
P:=Waher.Service.IoTBroker.XmppServerModule.PersistenceLayer.CreateAccount("",Str(NewGuid()),RandomPassword(),"","",Request.RemoteEndPoint);
Account:=P.Key;
AlternativeNames:=P.Value
)
while !exists(Account);
Code:=Account.GetOnboardingUrl(Now.AddDays(3));
CodeUrl:=Waher.IoTGateway.Gateway.GetUrl("/QR/"+UrlEncode(Code)+"?w=400&h=400&q=2");
QrCode:=Get(CodeUrl);
QrCodeFileName:=BatchFolder+"\\"+Left("00000000",9-len(AccountNrStr))+AccountNrStr+".png";
SaveFile(QrCode,QrCodeFileName);
Record:=
{
"AccountNr":AccountNr,
"UserName":Account.UserName,
"OnboardingUrl":Code,
"QrCodeUrl":CodeUrl,
"QrCode":QrCodeFileName
};
PushLast(Record,Records);
AccountNr++;
);
Accounts["Records"]:=Records;
SaveFile(Accounts,BatchFolder+"\\Accounts.json");
AccountsXml:=<Accounts nrAccounts=N created=Created>
<[[foreach Record in Records do
<Account accountNr=(Record.AccountNr) userName=(Record.UserName) onboardingUrl=(Record.OnboardingUrl) qrCodeUrl=(Record.QrCodeUrl) qrCode=(Record.QrCode) />
]]>
</Accounts>;
SaveFile(AccountsXml,BatchFolder+"\\Accounts.xml");
);
The TAG ID Onboarding API has been updated to allow for resending verification codes, without generating new codes. There are two parts of this API:
For clients that access an onboarding Neuronยฎ, the /ID/SendVerificationMessage.ws resource has been updated to allow for resending codes, by providing an Resend property in the request. If set to true, the resource will resend any existing code to the registered components, otherwise an error will be returned.
The /ID/SendVerificationMessage.ws now accepts payload having the following format:
{
Nr:Optional(Str(PNr like "\\+[1-9]\\d+")),
EMail:Optional(Str(PEMail like "[\\w\\d](\\w|\\d|[_\\.-][\\w\\d])*@(\\w|\\d|[\\.-][\\w\\d]+)+")),
AppName:Optional(Str(PAppName)),
Language:Optional(Str(PLanguage)),
Resend:Optional(Bool(PResend))
}
If the Resend property is available, and is true, the method will resend any existing code to the existing number or e-mail address provided. It is not possible to send an existing code to a new number or e-mail address.
Agent API
The Agent API (from build 2025-06-02) now has a new resource: /Agent/Account/ResendVerificationCodes. This resource allows for the resending of verification codes for the account currently being created. In order to access it, the JSON Web Token (JWT) provided in the response when creating the resource must be provided. The caller also needs to provide the phone number and/or e-mail address to which codes should be resent.
Security Notice: It is not possible to resend codes for accounts, numbers or e-mail addresses that have been verified. You can only resend codes for accounts still pending verification. This includes partially verified accounts. If the phone number has been verified, but the e-mail address has not, or vice versa, you can resend the code for the unverified part, but not for the verified part. Attempting to resend codes that have been verified, will be flagged, and repetetive calls to resend codes for verified accounts, numbers or addresses may result in the temporary and then permanent blocking of the endpoint making the call.
The Onboarding API has been updated to provide some additional IP Location information during onboarding, to help clients prefill fields in ID applications.
When calling the https://id.tagroot.io/ID/CountryCode.ws web service (using POST, and Accept header set to application/json), the following information will now be available in the response:
The IP Location information is provided by IP2Location.
Note: The information provided in the response may be incorrect, so users will need to verify the information provided, before including it in any ID applications.
As of build 2024-01-16 configuring the Onboarding Neuron® has been refactored. Articles earlier written on the subject (which have now been updated accordingly) include:
The purposes of hosting an Onboarding Neuron® include:
Acting as the first contact point for a client application (such as a digital ID), helping the client to find a suitable service provider hosting their own Neuron®.
Validating e-mail and phone numbers.
Sending validation messages via e-mail and SMS.
Configuring Onboarding Domain
You now configure the domain name of the Onboarding Neuron® under the Notarius Electronicus menu (previous versions had a Neuro-Access button under the Software menu, which has been removed):
Onboarding Menu
Clicking on this menu item opens a simple dialog where you enter the domain name of the Onboarding Neuron® you want to use:
You can also access the service from the Admin menu, by pressing the Neuro-Access button:
Neuro-Access Button
Configuration of the Onboarding Neuron®, used by this service, has been moved to the Neuron® itself. See the article Configuring alternative onboarding Neuron for more information.
Onboarding process
During the onboarding process, the user validates its e-mail address and phone number with an onboarding Neuron®, who directs the app to the most suitable host for the Neuro-Access account. If the user chooses to create a simple Neuro-Access digital identity (i.e. only containing the phone number and e-mail address provided) the digital identity can be automatically approved, if the host Neuron® is able to validate the information with the onboarding Neuron. This service performs this task: It registers an Identity Authenticator with the Neuron®, which authenticates such simple Neuro-Access digital identities with the onboarding Neuron®, and approves the applications automatically, if the information matches the information validated during the onboarding process.
Configuration page
The configuration page for the service is very simply. All you need to do is provide the domain name of the onboarding Neuron® used. By default, the TAG ID Onboarding Neuron® will be selected.
Neuro-Access Settings
Configuration of the Onboarding Neuron®, used by this service, has been moved to the Neuron® itself. See the article Configuring alternative onboarding Neuron for more information.
