This document detailed out the design approach to integrate with the list of devices used in the MOSIP platform.

Interface approach has been taken to implement the integration with external devices. The interface should have the required method to communicate with the external devices. An Abstract class has been defined to implement the common functionality and it should be extended by Vendor specific implementation class. The device vendor's specific implementation class should extend the Abstract class and implement the required methods using available libraries.

Devices:

1. Scanner

2. Printer

3. GPS

Scanner:

Interface: IMosipDocumentScannerService

1. public Boolean isConnected() - to check the scanner connection availability.

2. public BufferedImage scan() - to scan the document from the scanner device.

Abstract Class: DocumentScannerService

1. public byte[] asPDF(List bufferedImages) - to convert the captured scanned document files into pdf format.

2. public byte[] asImage(List bufferedImages) - to convert the captured scanned document files into image format.

3. public byte[] getImageBytesFromBufferedImage(BufferedImage bufferedImage) - to get the byte[] from BuffredImage object.

4. public List pdfToImages(byte[] pdfBytes) - to convert the pdf document to image format in order to show in the document preview.

Printer:

Use the JavaFx provided print functionality to interact with printer directly from UI layer. No additional interface is required. javafx.scene.web.WebView.getEngine().print(PrinterJob)

GPS:

Interface:IMosipGPSService

1. public String getComPortGPSData (String comPortNo, int portReadWaitTime) - it returns GPS signal in standard format.

Abstract Class:IMosipGPSServiceImpl

1. public GPSPosition sigalParser(String line) Inputs: gps signal (Ex: $GPRMC,055218.000,A,1259.4845,N,08014.7602,E,0.07,120.70,171018,,,A*64)

   • returns the latitude and longitude from the GPS signal.

Steps to generate the first User in MOSIP eco-system, refer below for the process:

1. Creating the First User in KeyCloak

• First the role "Default" need to be created in KeyCloak with all other roles.

• A User say 'X' has to be created in KeyCloak and the role “Default” needs to be mapped to it.

2. Creating the Relevant Master Data

• All data required as part of ID Object, for example, Gender, Location hierarchy, templates, etc. should be setup in the database through the CSV Utility

• Master data of user, machine, device and center should be created and uploaded through the CSV Utility (Note - the user id for the User 'X' should be present in Master data of User)

• All necessary center-machine-device-user mappings should be completed through the CSV Utility for the first user.

3. Creating the First User in MOSIP

• The User 'X' should now download the latest Registration Client and login with the credentials set in KeyCloak.

• The User will automatically skip Operator/Supervisor On-boarding and will reach the home page of Registration Client.

• The User authentication method for User 'X' will be always User ID and Password as it is the default user.

• The User now can register himself/herself in MOSIP and will get an RID and UIN.

4. Allocating the RID to the User Created in KeyCloak

• The RID created for the User 'X' needs to be updated in KeyCloak.

5. User On-boarding

• The role for the User 'X' needs to be changed to Registration_Officer or Registration_Supervisor.

• The role "Default" needs to be removed from KeyCloak so that no other user has the role Default.

• The User 'X' can now login to Registration Client (from the mapped Machine/Centre) with the above Username/Password.

• The User now would need to On-board as his/her role would be changed.

• Once on-boarding is completed User 'X' can register the subsequent Officers and Supervisors.

• The User details of the subsequent Officers and Supervisor must be created in KeyCloak with appropriate roles assigned (as per Step 1) and their RIDs should be mapped in KeyCloak (as per Step 4) so that they can login to Registration Client.

Flow chart describing first user onboarding

Operators in MOSIP

The operators is the one who can login to the registration client application and perform various activities. The roles associated to an operator in MOSIP can be of a Supervisor or an Officer. Below are features accessed by a supervisor and an officer in the registration client.

Operator on-boarding

When an operator tries to login to his/her registration client for the very first time they need to be online and would be re-directed automatically to the on-boarding page. During on-boarding the operator needs to provide his/her biometrics, which would be stored and mapped to the client machine locally post authentication.

Operator's biometrics are captured during on-boarding to support login using biometrics, local duplicate checks, and registration submission via. biometric authentication in registration client.

Login & Logout

First time login

When an operator whats to login to the registration client for the first time, he/she needs to have the registration client in online mode. The first time login for any user in registration client is mandated to be using user name and and password based login. After the first login and successful on-boarding; the registration client would mandate the operator to login with the configured mode decided by the administrator.

Modes of login

MOSIP supports single factor and multi factor login including password, OTP, iris, fingerprint, and face authentication for registration client. An administrative configuration setting determines the mode of login.

The registration client can authenticate an operator in offline mode using the locally stored biometrics (face/finger/iris) & password, but it has to be online to authentication an operator using OTP.

Temporarily lock the operator

The registration client temporarily locks the operator’s account in case he/she provides an invalid password, fingerprint, iris, face for five times continuously to login. The temporarily account lock lasts for 30 minutes (which is configurable).

Logout

An Operator can logout of the registration client by just,

• Clicking the logout button,

• Closing the registration client, or

• Being in-active on the registration client for configured amount of time after which he/she is automatically logged out.

Upon logout, any unsaved data will be lost. Data will not be automatically saved in the database and will not be retained in memory though transaction details which is used for auditing will be captured & stored (except for PII data).

Data Sync

Master data sync

In order to run the registration client application in online or offline mode it need some master data. When the client machine is switching from offline to online mode, the locally saved data can be synced with the server & changes from server can be synced backed to client. The data sync can happen through an automated process at a set frequency or an operator can manually initiate a sync.

Configuration sync

When an operator performs data sync the configurations related to registration client also gets synced. Based on the configuration (turn on or turn off), the system allows the operator to capture applicable biometrics, authenticates, and completes the registration activities.

Client to server sync

Registration Client syncs back some information back to the server whenever a sync is triggered:

1. Operator on-boarding details such as mapping of user, machine & center.

2. List of registration packets that are newly created.

3. The registration packets are also uploaded to the registration processor.

Packet status sync

During the sync operation the registration client request for the registration server for the status of some of the packets that it has already synced in the server. Knowing the status of the packets helps the registration client to,

1. Delete the packets from it's local file system based on the countries policy.

2. Re-Upload the packet if it is missing in the server.

3. Inform the resident to re-register if packet processing fails in server.

Pre-registration data download

An Operator can download the pre-registration data of his/her center for a date range (current date - end date) while being online (where the date range is configurable) and store it locally in the registration machine for offline use. Now when the system is offline and the pre-registration data is already downloaded; the operator can enter the pre-registration id to auto-populate the registration form with the demographic details of the resident.

Now if the registration machine is online the operator can enter the resident's pre-registration data in real time irrespective of the center selected by the resident while filling the pre-registration form.

Health check

Peripherals check

The registration client has the provision to show if the registration machine has internet connectivity or not.

Disk space check

Upon receiving a request to create a registration packet at the end of data capture and authentication steps, registration client validates if the disk space available on the registration machine to store the registration packet is sufficient or not. If disk space is insufficient, registration client displays an error message and data entered by registration officer is not saved. Then registration officer needs to clean up the registration machine to make sufficient space and try the registering the resident again.

Virus scan/Security scan

When the registration client application is open, the application scans the registration packets at a configured frequency for viruses. If the registration client application is not open at the configured time, the scan will be queued up and will run when the client application is open.

Registration services

New registration

An operator can initiate the process of registering an new applicant in the MOSIP ecosystem by filling the new registration form with the resident. Below are few of the processes needed to complete a new registration.

Enter demographic data and upload documents of a resident

If the resident has a pre-registration id, the operator can auto-populate the demographic data and the documents by entering the pre-registration id.

If the resident doesn't have a pre-registration id, the operator can enter the resident’s demographic details (such as Name, Gender, DOB, Residential Address, etc.) & upload the documents (such as Proof of Address, Proof of Identity, Proof of Birth) based on the ID Object defined by the country.

After the demographic details are entered the registration client validates the entered demographic data as per the Id validation rules defined in the ID Object UI Specification and appropriate error messages are shown in case the validation fails.

Capture biometrics of a resident

The capture of biometrics is governed by the country, i.e. capture of each modality (fingerprint, iris or face) can be controlled by the country using the global configuration to turning on or off, capture of a particular biometrics.

When the operator clicks on the capture button and tries to capture the biometrics of the resident, the device needs to make the capture when the quality of the biometrics is more than the threshold configured by the country. The device will try to capture the biometrics until the quality threshold has crossed or the device capture timeout has crossed which is also configurable.

Post the timeout has occurred and the captured quality of biometrics is less than the threshold, registration client provide an option to the operator to retry capture of biometrics but for a particular number of times which is also configurable.

If the resident has a biometric exception (resident is missing a finger/iris or quality of finger/iris is very poor) the resident can mark that particular biometrics as exception but the resident has provide an exception photo after providing the biometrics.

Device validation

The biometric devices connected to the registration machine to perform registration needs to registered devices and hence device validation is a very important process. The devices are validated using the master data that is received from the server during sync. Once the validation is successful and the device is connected to the registration machine a three way mapping of the center, machine & device is created and synced back to the server.

Capture consent from the resident for data storage and utilization

For every registration, the registration client provides an option for the operator to mark an individual's consent as Yes or No. The operator marks consent after confirming with the resident. Whether the consent is marked as Yes or No, it will not have any impact on issuance of UIN for that resident and the registration processor will not execute any validations in this regard during packet processing.

New registration for an infant

The registration flow for an infant is slightly different from that of registering an adult. The categorization of normal resident and infant is determined based on the age calculated by when the resident provides the date of birth. The age of infant is a configurable parameter (in the current configuration age of infant is set to 5 years).

For an infant registration client doesn't collect the biometrics (except for photo) but it collects the parent/guardian UIN or RID and biometrics for authentication in the server side. Apart from parent/guardian details the resident need to provide a Proof of Relationship document defined by the country.

Update resident's details

When a resident visits the registration center to update his/her demographic or biometrics details, the operator captures the updated data as provided by the resident in the registration client.

Process Flow using which data gets captured by registration client for updating a resident's data:

Find a lost UIN

There might be a situation when a resident might have lost his UIN and visits the registration center for retrieving the same, the operator then captures the biometrics and demographic details of the individual and processes a request to retrieve the lost UIN. The system sends a notification to the individual upon successful creation of the UIN retrieval request.

Acknowledgement and Notifications

Printing the registration receipt

Once the registration process (new registration, UIN update or lost UIN) is completed, the registration client generates an unique request id and a registration receipt which contains labels & data in configured language. This data also contains a QR code of the RID, photograph of the resident and ranking of each finger from 1 to 10 (1 being the finger with the best quality). This receipt is print friendly and can be used for printing using any printer.

Sending email and SMS notifications

Once a registration process is completed, a notification is sent to the resident using the email ID and mobile number that was provided as part of demographic data. This notification sent is driven by a template created as part of master data and the language selected (primary, secondary or both) & notification mode (SMS, Email or none) is driven by configurations.

Registration Client also provides an option to send SMS and email notifications to additional recipient\s (other than the individual’s primary email ID and mobile number).

Use of biometric SDKs in registration client

Local biometric authentication for operators

Registration client perform authentication for registration officers and supervisors during various scenarios in registration client. In order to perform authentication using biometrics in such scenarios registration client need to integrate with a biometric SDK. The scenarios where biometric authentication is performed in registration client are:

1. When operator wants to login to registration client

2. When operator creates a packet

3. When an exception packet is created we need to perform supervisor authentication

4. When supervisor performs end of day verification

5. When supervisor performs resident about re-registration

Local biometric de-duplication

There could be a scenario where an operator in-order to show a demonstration to the resident might capture his/her own biometrics, which could let to packet processing failure in the server side. Hence, in order to avoid such cases we perform de-duplication of biometrics of the resident against the operator's biometrics who have on-boarded to that registration machine.

Registration officer and supervisor approvals

Approval for packet creation

An operator needs authenticate himself/herself when the registration process is completed. After successful authentication an encrypted packet is created in registration client. During this process if biometrics is used as the mode of authentication, the operator's biometrics is sent to server as part of the packet for verification in the server side.

Approval of exception packet

If a packet is created for a resident who has marked his/her biometrics as exception, the registration client performs a second round of authentication for packet creation. During this authentication the supervisor needs to provide his/her credentials. If biometrics is provided during this authentication, it is sent as part of the packet to the server.

Approval during "re-registation"

During pre-processing of the packet, if the registration processor finds an error in the packet such as decryption failure, then an individual will not be communicated automatically to re-register. In such cases, registration processor marks the status of the packet as "re-register" so that a supervisor informs the individual to "re-register" his/her application. After informing the resident the officer needs to authneticate himself/herself using his/her credentials.

Geo-location

We have a feature to capture geo location of a device before any registration is performed. This is driven by a configuration. If capture of geo location is turned on, the system performs the following steps:

• Validates that an on-boarded GPS device is connected to the machine.

  • If an on-boarded GPS device is not found, then displays an error message.

  • If more than one on-boarded GPS device is connected, then proceeds with the first GPS device that the system finds as it scans the ports of the machine.

• Requests the GPS device to capture a location.

• Receives the latitude and longitude from the GPS device.

  • If signal is weak and GPS device is unable to capture location, then displays an error message.

• Proceeds to perform following validations:

  • If location capture is required only at the beginning of day, the co-ordinates are stored and validations are performed when opting to start a new registration.

  • If location capture is required only at the beginning of day and location could not be captured at beginning of the day, then attempts to capture the location during the first registration of the day.

  • The latitude and longitude will be stored in the packet when the packet is created.

• System captures and stores the transaction details for audit purpose (except PII data).

Language Support

The Registration Client supports two languages, a primary language in which all pages of the application are rendered, and demographic details of an individual are also rendered in secondary language for convenience of the officer. The default primary and secondary languages are driven by an administrator configuration and can be setup by the admin as required. Transliteration from the primary to secondary language is supported for registration officer entered text fields.

In the below listed scenarios, system will render an error message on the Login page and inhibit Registration, and hence, the language configurations should be appropriately setup by the administrator.

• If Primary Language is set to a specific value and Secondary Language is not set by Admin, or

• If Secondary Language is set to a specific value and Primary Language is not set by Admin, or

• If both Primary and Secondary Language are not set by Admin

This error message will not have an option to exit, hence not allow the user to proceed further. On page refresh, the system will render the error message again and hence, inhibit registrations. Therefore, it is important for the administrator to setup the configurations appropriately. In case configurations are setup correctly, but post Login, if a sync is initiated through the option in the homepage, and then if it is identified that either Primary/Secondary language/both are not defined, then the system will render the same error message on the homepage and not allow the user to proceed further.

Considering a scenario, wherein if Primary language and Secondary language is configured to be the same, EG: English then:

• The system will render the demographic page (with both left and right side for Primary and Secondary language) in the same language

• Values entered on the left side (Primary Language) will not be transliterated but auto-copied on the right side

• Values on the right side will remain un-editable

• As part of the packet, system will send/store data in one language only, if language code is identified to be the same – EG: ENG (English)

Therefore, it is important for the administrator to setup the configurations appropriately.

Translation

A Registration Officer can view static data translated to secondary language.

• In MOSIP, the primary and secondary languages are configured by the admin.

• Admin configures all the static data in both primary and secondary languages so that the registration officer can view all the pages of client application in primary (default) and second (translated) languages.

• If the both languages are configured in one language, the system displays the text in default language only.

Transliteration

Registration Client enables viewing transliterated data.

The Registration Client application supports two type of languages: Primary language (the language in which the registration officer enters data) and secondary language (transliteration language). The secondary language is country specific and is set by the administrator.

When the officer starts a new registration, update or lost UIN process and provides demographic data (Full Name, Address Line 1, Address Line 2, Address Line 3, and parent/guardian Name) of an individual in the primary language. The system transliterates the data and displays in the corresponding secondary language fields.

An Officer can invoke the virtual keyboard to edit transliterated data and proceeds with registration. The following rules are followed during transliteration.

• Editing transliterated language does not change the data entered in the primary language.

• The system also validates the maximum character length in the transliterated language and in primary language.

• If secondary language is not configured, the system does not do any transliteration and will display empty space instead.

• Numeric data are not transliterated. The same numeric data are displayed in the secondary language section of the page, which are not editable.

Master data selections are not transliterated. Instead, the master data as setup in the secondary language is displayed in the relevant section.

The system then enables the officer to view the registration confirmation page. The data, which are transliterated and edited earlier are also shown in the secondary language.

Packet Upload

Registration Packet Upload

Upload the packet

• The system allows a registration officer to view a list of packets and may opt to upload one or multiple packets from a list of packets.

• After the registration officer selects the packet(s), he/she can upload the selected packet(s) to server.

Push those packets that are marked 'Resend' to the server

• When the registration officer or supervisor navigates to the ‘Upload Packets’ page, the list of RIDs that are pending packets to upload will be displayed.

  • Pending packets are those packets, which are not sent to the server due to various reasons (e.g. Sanity Check and Validation failure in the Registration Processor) and have been marked for resending.

• When the registration officer or supervisor selects the ‘Upload’ option, the pending packets will be uploaded to the server.

• The result of each packet uploaded will be displayed as ‘Success’ or ‘Failure’.

  • Packets that are successfully sent or resent will not be sent again unless the server requests for them.

  • Packets for which upload fails will continue to be in pending state.

• System captures and stores the transaction details for audit purpose (except PII data).

Enable a real time packet upload when system is online upon registration submission

• When EoD process is turned ON

  • Registration Client checks if the system is online as soon as the assigned approver (such as supervisor) approves or rejects a new registration or UIN update.

  • If client is online, the Registration Client sends Registration ID to server and then the packets are marked as “Ready to upload” and auto uploaded to server.

  • If client is offline or on low bandwidth, then when the client next comes online, the Registration ID’s are sent to server through scheduled or manual sync and the packets are then marked as “ready to upload”.

  • Once the packets are ready for upload, packets are uploaded in two ways:

    • The registration officer can initiate upload to server using upload function.

    • Export to external storage device for subsequent upload as required.

• When EoD process is turned OFF

  • Registration Client checks if system is online as soon as the registration officer submits a new registration or UIN update.

  • If client is online, the Registration Client sends Registration Id to server and then the packets are marked as “Ready to upload” and auto uploaded to server.

  • If client is offline or on low bandwidth, then when the client next comes online, the Registration ID’s are sent to server through scheduled or manual sync and the packets are then marked as “ready to upload”.

  • Once the packets are ready for upload, packets are uploaded in two ways:

    • The registration officer can initiate upload to server using client’s upload function.

    • Export to external storage device for subsequent upload as required.

Packet Exporter & Offline Upload from External Device

Export Packets to External Device

System exports registration packet data from client machine to an external device as follows:

• This feature allows the registration officer to select a destination folder to export the packets. By default all packets that are listed/eligible to be uploaded, are exported to the external device

• The destination folder includes the laptop/desktop, an external hard drive or a remote location

• External storage devices are not necessary to be MOSIP-registered devices

• When the destination folder is selected, registration officer initiates export of packets

• System exports the packets to the selected folder and performs the following steps:

  • Identifies the packets in ‘Ready to Upload’ state.

  • If EoD process is turned ON, packets that have been approved or rejected and packet ID sync is completed are considered ‘Ready to Upload’

  • If EoD process is turned OFF, packets are considered ‘Ready to Upload’ as soon as the registration is submitted and packet ID sync is completed

  • Puts the packets in the destination folder

• All the Registration Officers and supervisors on-boarded to the client machine will be able to export all packets

• Supports the partial export. If the system is able to export some packets to the folder and no other files due to lack of storage space or unavailability of the folder, the successfully exported packets will remain in the destination folder.

• For partial or full failure, the system displays error message

Upload Packets from External Device to Server (To be Developed)

Once the server acknowledges that the packets have been received (which is uploaded from the external device to the server through a defined mechanism - Yet to be defined/developed), the packets in the client will be marked as ‘Uploaded’ upon the next sync with Server.

• Packets that remain in ‘Ready to Upload’ status will be exported again when the next export is executed.

• Packets in ‘Uploaded’ or any other status will not be exported again.

Analytics and Audit Logs

System captures and stores details of each transaction during registration process for audit purpose (except PII data). The audit data is stored in the audit database. When the client machine is working in an offline mode, the audit log is synced with the server as when the client machine is online.

Data Security

Registration Client integrates with Trusted Platform Model (TPM) data integrity. For enhanced security and integrity purposes, data captured from individuals are saved securely in local system and then shared to server. The details saved locally will be encrypted. Database encryption is also mandatory.

MOSIP performs the following:

1. Signing the data (This process is called as Signature) using Private Key provided by the TPM

   • This process will ensure that the request to the server has been dispatched from a registered or trusted Registration Client machine

2. Validates the signature against the actual data using the Public Key or Public Part. The application does not connect or access the underlying TPM to validate the Signature. This validation ensures that the request is from a registered or trusted Registration Client machine

3. Encrypts and decrypts the data using RSA algorithm in TPM. System security and tampering of packets

The system uses a machine and centre specific public key to encrypt. Only the server which has the respective private key, machine id and centre id can decrypt the encrypted packet. The data stored in database and application binaries are encrypted using TPM public key and registration officers will not be able to access directly.

Installation and Software Version Upgrade

A. Registration Officer or Supervisor can download and unzip the client application set up kit

For initial installation of the client software on a particular machine, supervisor or registration officer will download an installable software (setup kit). Then unzip the setup kit and install it in the client machine.

When a registration officer or supervisor opts to download setup kit and selects the OS-specific setup kit to download, the system allows the registration officer to download the setup kit to the storage location chosen by the registration officer.

1. Registration officer then unzips the setup kit.

2. Extract the files and folders from the zip file to the chosen location.

3. Allows the registration officer to verify that the files and folder structure are as described in the design document.

4. System captures and stores the download transaction details for audit purpose (except PII data).

B. Update the client software from the server

If a software update is available, then the system will provide an option to supervisor or registration officer to update either immediately or later. If the maximum number of days without software update has been exceeded, then the system will mandate a registration officer to update the software.

The system follows the following steps during the update process:

1. When the client is online, the system automatically checks for updates if available.

2. If an update is available, the system displays a message “Updates are available” and provides two options to the registration officer

   • Update now or

   • Update later.

3. If the registration officer opts to select “Update now” option, then the registration officer can download and installs software and launches the application.

4. The updates are downloaded as patch updates.

5. When installation is in progress, the registration officer cannot perform any action on the client.

6. Once installation is completed, the registration officer can start working on the client.

7. If update is not successful, the system provides error message and provides both the options (Update Now or Update Later) again.

8. If the registration officer opts to select “Update later” option, then the system checks if the freeze period has been reached.

   • If the freeze period has not been reached, the system allows the registration officer to continue with registration

   • If freeze period has been reached, the system does not allow the registration officer for registration without updating the software.

   • The client will be locked for registration, if x days (configuration setting) have passed since the last check for updates and mandates the registration officer to update the software.

9. If updates are not available, the system launches the application.

10. If update is not successful, the client returns to its earlier version.

11. System captures and stores the transaction details for audit purpose (except PII data).

Clean up

Pre-registration and registration data are automatically deleted from the client machine upon consumption and upon intimation from the server respectively.

• Pre-registration data is deleted from the client machine immediately after consumption for a registration.

• Registration packets that are identified as ‘processed’ are deleted by a periodic process.

• Audit data is deleted after it is sent to the server.

• All deletion is executed by a periodic process after retention of the data for a configured duration.

Data retention policies

A. Read packet status and delete packets

When the Registration Client receives a request through manual trigger or scheduled job to sync data, the system performs the following steps to read a packet status and delete the packets:

1. Sends the data sync request to server.

2. Receives response from server with packet statuses.

   • Server sends status of those registration packets that were created in the specific machine, and that status that has changed since the last sync.

3. Saves the statuses ‘Processing’, ‘Processed’ or ‘Resend’ as received for each packet. Statuses of other packets are not updated.

4. Immediately deletes the packets from the local machine whose status is received as ‘Processed’.

5. Displays an alert in case of sync failure.

   • The on-screen message is only indicated if the sync was a success or failure.

   • Detailed errors can be viewed in the transaction logs.

6. The system does not allow registration officer to perform any activities when the data sync is running.

7. If the Registration Client is not online or not open during a scheduled sync, the sync will be queued up and will be executed later.

8. When the Registration Client is next launched and is online, checks if the previous scheduled sync was executed. If not executed earlier, then immediately starts the sync.

9. System captures and stores the transaction details for audit purpose (except PII data).

B. Delete transaction history (audit logs) post sync with server and the retention period

When a set of audit data is uploaded to the server and the server has acknowledged receipt of the audit data, the system performs the following steps to delete transaction history (audit logs) post sync with server and the retention period:

1. Runs on a daily process to identify audit data that has been sent to the server and acknowledgement is received from the server.

   • The audit data acknowledgement received from the server >= x hours ago. X is configured at a country level.

2. Deletes the identified audit data from the client machine.

3. Executes at a time and frequency as configured.

   • The process takes place only when the Registration Client is in open and running situation. If the Registration Client is not open during a scheduled run, it is executed as soon as the client is next started up.

4. Does not delete audit data, if that is yet to be sent to the server.

5. System captures and stores the transaction details.

Machine Retirement

Machine is termed as machine retirement due to following reason:

• If the machine has obsolete specification.

• When the machine is moved from one center to another (re-mapped), then the machine will retire from that old center.

Before the machine is decommissioned, the following checks must be performed:

1. All packets created must either be uploaded to server or exported to external device.

2. All pending end of day approvals are completed and re-registrations pending action are cleared, refer below for more details

3. All data locally saved in the machine must be cleaned up.

Re-mapping of Machine:

If a Machine has been re-mapped to another center, then:

1. Officer will not be allowed to do any operation in Registration Client except,

   • Login/Logout

   • Approve packets as part of End of Day Approval process

   • Upload Packets

   • Inform Residents to Re-Register and mark action accordingly

2. Once Packet Approval and Informing Resident is Completed, then

   • Packets will be auto uploaded if anything is pending

   • Initial Sync Flag is Turned On

3. Once the Officer logs out and tries to login again, then

   • New Master data gets downloaded for the newly mapped Center

This document contains the 'Registration Client' application initial setup, update and configuration process.

Registration Client application is a desktop based application, that can be used to captures the demographic and biometric details of a resident along with supporting information (like proof documents & information about parent/guardian/introducer) and packages the information in a secure way using RSA based algorithm. The information packet can be sent to the server in an online or offline mode for processing.

The registration client application leverages the TPM capabilities and secure the data and mark the senders identity in the request before sending to external system. The MOSIP server would validate the request and make sure that the request is received from the right source. Every individual machine's TPM public key should be registered at MOSIP server to accept and process the data send by them.

A Trusted Platform Module (TPM) is a specialized chip on a local machines that stores RSA encryption keys specific to the host system for hardware authentication. Each TPM chip contains an RSA key pair called the Endorsement Key (EK). The pair is maintained inside the chip and cannot be accessed by software. By leveraging this security feature every individual machine would be uniquely registered and identified by the MOSIP server component.

Application build

OpenJDK version "11.0.8" version to build the application.

Registration Client application is built with four different modules

• registration-client - it contains only UI related code.

• registration-libs - it contains the code to generate the initial run.bat.

• registration-MDM-service - MOSIP Device Manager service to integrate with BIO device and render the required data in a standard format and that will be consumed by the 'registration-services' module.

• registration-services - it contains the Java API, which would be called from UI module to render the services to the User and capture the detail from User and store it in DB or send to external systems through services.

Prerequisites

System prerequisites

• CPU - Dual Core Processor - 2GHZ

• Ram - 16 GB

• Local Storage Disk Space - 500 GB

• USB 2.0 ports or equivalent hub.

• Physical machine with TPM 2.0 facility.

• Windows OS [10 v]

Application Prerequisites

Before running the 'Registration Client' application, following prerequisites to be completed:

• All Master data should be loaded at MOSIP Master database.

• User, machine, device & center mapping, and all other required table and data setup should exist in MOSIP Master database along with the profile and desired roles configuration in IAM server.

• User's machine should have online connectivity to access the client_upgrade_server, where the application binaries are available.

• If TPM enabled, a logged-in user to windows machine should have permission to get the public key from TPM device.

• Through the sync process, the data would be updated into the local database from the server.

Anti Virus - ClamAV Setup and Configuration in local machine

Installation of Open Source Anti Virus Software [ClamAV]:

• Install the downloaded .exe file.

ClamAV Config Setup

• Rename the clamd.conf.sample to clamd.conf from the installed directory of ClamAV. Ex: C:\Program Files\ClamAV\conf_examples\clamd.conf.sample file save as C:\Program Files\ClamAV\conf_examples\clamd.conf

• Rename the freshclam.conf.sample to freshclam.conf from the installed directory of ClamAV. Ex: C:\Program Files\ClamAV\conf_examples\ freshclam.conf.sample file save as C:\Program Files\ClamAV\conf_examples\ freshclam.conf

• Comment the line# 8(Example) in both the files

• Download the Antivirus database from the following urls and placed it in the database folder(C:\Program Files\ClamAV\database)

  • http://database.clamav.net/main.cvd

  • http://database.clamav.net/daily.cvd

  • http://database.clamav.net/bytecode.cvd

• Update Config files:

  • clamd.conf file changes:

    • Uncomment LogFile "C:\Program Files\ClamAV\clamd.log"(Line 14)

• freshclam.conf file changes:

  • Uncomment the below mentioned lines in the file,

    • DatabaseDirectory - "C:\Program Files\ClamAV\database"(Line 13)

    • UpdateLogFile - "C:\Program Files\ClamAV\freshclam.log"(Line 17)

    • DatabaseMirror - db.XY.clamav.net(Line 69) change XY to our country code [Eg: IN]

    • DatabaseMirror - database.clamav.net(Line 75)

    • Checks 24(Line 113)

    • LocalIPAddress aaa.bbb.ccc.ddd(Line 131) change to our machine IP address

• Once all the Configurations are done run the freshclam.exe and then run clamd.exe. If required, restart the machine.

Registration Client Installation

Download - Application Initial Setup file

• User downloads registration client zip from https:///registration-client//reg-client.zip.

• Once downloaded then unzip the file into a particular location. It contains the following folder structure.

  • bin: It contains the client UI and service binaries in an encrypted format.

  • lib: It contains the library required for the application to run.

  • cer: It contains the certificate used to communicate with the MOSIP server.

  • run.bat: batch file to launch the application.

  • jre: It contains the java runtime engine along with the required DLLs.

• Set "mosip.hostname" environment variable, with domain name being the value to be used by registration-client.

• Click the 'run.bat' to initiate the setup process.

When the user clicks on the 'run.bat' it does the following:

• Communicate with client_upgrade_server through a secured connection and download the maven-metadata.xml file to identify the latest jar versions.

• Compare the checksum of the local version of jar files with the data present in the Manifest.mf file.

• Identify the list of binary files and Download the required jars.

• Once download completed, decrypts the UI and service jars and start the application.

Application Startup

• Once after application launches, TPM is initialized with RSA endorsement keys when TPM mode enabled / fallback implementation is initialzed ('reg.key', 'reg.pub', and 'readme.txt' will be created in your user.home directory with under .mosipkeys folder).

• On initial startup, DB and DB pwd is autogenerated. DB password is secured using TPM key and encrypted db.conf is saved under .mosipkeys folder inside user.home directory.

• Use TPM public key / from readme.txt copy the public key and machine name (hostname) and use it in machine's update API.

• User should initially be online to validate their authentication against the MOSIP server. Post which, the sync process would be initiated.

• Once the sync process completed then restart the application to pick the local configuration.

• User should perform the self onboarding before start using the application.

Update process

The application refers to the 'maven-metadata.xml' to verifies any new version exists or not.

mosip.rollback.path - Make sure that the rollback path is provided in this variable, which is available in 'spring.properties' file; as part of the registration-services module.

Application update

• During the startup of the application, the software check will be validating against the maven-metadata.xml file from client_upgrade_server. If any diffs found, the application prompts the user with 'Update Now' or 'Update Later' options to install immediately or later. Apart from this, there is another menu option available in the application to trigger the 'Update' process post login to the application. The update process would update both the application binaries and DB.

• During the update process, the running application refer to the 'rollback' path and take the back up of 'lib, bin, MANIFEST.MF' files inside rollback folder with the new folder as 'Version_timstamp' format.

• Download and Update the required binary libraries and DB script into the existing running folder and restart the application.

Database update

The database update can be rolled out through the binary update process. If any changes in the script then the respective script would be attached inside 'registration-service/resource/sql/version folder [like: 0.12.8]' and deliver the jar with the newer version. During the update process, the jar would be downloaded and script inside the jar would be executed. It would also contains the 'rollback' {registration-service/resource/sql/version folder_rollback [like: 0.12.8_rollback]} script if update process to be rollbacked due to any technical error.

Configuration

The application provided with the facility of multiple configurations for a different set of parameters. Each attribute level configuration changes should be performed at 'Config' server and same should be sync to the local machine through kernel services. Here few of the configurations are listed out that provide the facility to enable and disable the biometric.

Registration Configurations

Global Configurations

TPM [Trusted Platform Module]

To enable or disable the TPM functionality, modify the mentioned key in 'registrtaion-libs/props/mosip-application.properties' file.

mosip.reg.client.tpm.availability = { Y - to enable the TPM, N - to disable the TPM}

MDS [Mosip Device Service]

It integrates the Registration application with biometric devices (Iris/ Fingerprint/ Face).

Network Connectivity Check

Registration client verifies the below-configured URL to check whether the system is in online or not. The application uses this URL to perform the health check before communicating with the external services.

Property file

Property attributes and the respective sample values are provided below. Before building the registration-services, the required below properties needs to be changed.

File Location: /registration-libs/src/main/resources/props/mosip-application.properties

• mosip.reg.client.url={Reg client download url from client_upgrade_server }

• mosip.reg.logpath=../logs

• mosip.reg.packetstorepath={where the registration packet should be stored}.

• mosip.reg.healthcheck.url={Application uses this url to perform the health check before communicating with the external services. Default value: https://${environment}/v1/authmanager/actuator/health}

• mosip.reg.rollback.path={where the application backup should be taken during software update} [Default: ../BackUp]

• mosip.reg.cerpath=/cer//mosip_cer.cer

• mosip.reg.xml.file.url={client_upgrade_server url with maven-metadata.xml file}

• mosip.reg.app.key={contains the key to be used to decrypt the application binaries during run time}

• mosip.reg.client.tpm.availability={ Y - to enable the TPM, N - to disable the TPM, default N}

Dependent services

In Registration client application, only user mapping to the local machine can be performed. Rest of the data setup should be performed at MOSIP Admin portal. Through sync process the data would be sync between local machine and server based on machine's public key and center id. There are other services that are available to send the created packet from local machine to remote system.

External hardware driver(s)

This section covers the list of drivers required to communicate with the external devices.

• To integrate with Scanner, windows WIA libraries are used. So, the respective service should be running and also the scanner specific driver should also be installed.

• The application has been currently tested with CANON LiDE 120.

• Printer should be available to take the print out from application and the respective driver should be installed.

• Camera and the respective driver should be available to capture the applicant photo. Application tested with Logitech camera.

• When there is an integrated camera associated with the machine, it needs to be disabled.

• If GPS enabled through configuration then the respective device/ model specific driver should be installed to communicate through application.

This document describes the registration packet structure and the packet encryption procedure.

Registration Packet

Once a resident visits the registration center and provides their demographic & biometric details an encrypted zip file is created which is called a "Packet". This packet can only be decrypted by the registration processor using a private key available in the Kernel Key Manager.

The below diagram depicts the packet creation flow using the packet manager.

Packet Structure

Encrypted ZIP File

The packet name here is also the request ID that is generated for a request created when a resident enrolls into MOSIP, requests for updating data or request for finding his/her lost id. The request ID is a 29 digit number derived from the Center ID (5 digits), Machine ID (5 digits), sequence number (5 digits), timestamp (14 digits).

Folder Structure

• Container: The container is the base folder in which the sub-packets are stored with their respective JSON files containing meta information.

• Sub-Packets: Inside the container we ideally have three packets named as ID Packet, Evidence Packet and Optional Packet. Data inside each packet is stored based on a property in ID Schema called "Field Category".

• Packet JSON: Each sub packet has a JSON file associated with it which contains the meta information of the respective sub-packet.

• ID Object: Each packet has an ID JSON attached with it which has basic demographic data of the resident, document names that were uploaded, information about the introducers or guardians, biometrics file names (of applicant, introducer, guardians) and the version of the ID schema used. Data for each ID JSON is populated based on the ID Schema property, "Field Category".

• Documents: The documents uploaded by the resident during registration or pre-registration is stored in respective folders as driven by ID schema.

• Packet Meta Information: A bunch of meta data is generated during the registration process like the officer's or supervisor's id, machine details, device details, gps location, etc. which is stored in the Packet Meta Info file in JSON format.

• Audit: The audit trails created during packet creation is logged and sent to registration processor to be uploaded in the audit database for analytics.

• Packet Hash: During the packet creation a hash of the data being collected is stored in these files so that the data can be verified when the packet reaches the server. We have two types of hash file, Packet Data Hash file & Packet Operation Hash file.

Packet Encryption Procedure

Before writing the packet into the local disk, the zipped content should be encrypted using Session and RSA public key (center specific) to secure the data. The same data can only be decrypted at server end where the private key is available.

• Session Key Encryption:

  • Session key generation is a randomly generated and sent to client as part of sync from server.

  • Pass the created Zip object [in-memory] through the AES-256 bit encryption.

  • Pass the Random Session Key as a seed to this AES encryption.

  • Get the Registration Officer Id from user context object.

• RSA Public Key Encryption:

  • AES Session key bytes pass through the RSA public key encryption.

• Use the "#KEY_SPLITTER#" as a key separator for the AES encrypted bytes and the RSA Public key encrypted Session key seed.

• Append the RSA Public key Encrypted Session Key, Key Separator to the AES encrypted bytes.

• Append the EO and machine information as a META-INFO JSON file and create another ZIP out of it. [Packet Zip + META-INFO JSON]

• Save the encrypted data as a ZIP in local file system under the defined location in configuration file.

Overview

The registration client is a thick Java-based client where the resident's demographic and biometric details are captured along with the supporting documents in online or offline mode. The captured information is packaged in a secure tamper-proof way and send to the server for processing.

Registration client must provide the following :

• Secure way of capturing an individual's demographic and biometric data. The captured data must be cryptographically secure such that the data cannot be tampered with. This is called a registration packet.

• Interfaces to biometric devices that comply to industry standards. This ensure that any device manufactured as per standards will work with MOSIP.

• Works in online and offline mode. In remote areas where internet connectivity is a challenge, the registration client must work in offline mode.

• Remote software update capability. There must be a way to self-update to latest patches/upgrades (bug fixes/enhancements) in a remote way. There could be hundreds of client instances running on laptops/desktops. Updates on all of them must be controlled a central server.

• Tamper-proof client software. The registration client must have an ability to validate the structure of the information captured so that it could detect any anomoly due to a possible manual tampering and reject the captured packet.

Detailed functionality

Process flow

Registration officer Onboarding

Registration preparation

Individual registration

Packet upload

End of day (EOD) process

UIN update

Lost UIN

Software update

Logical view

Component architecture

Registration packet structure

Registration client reference application

First user on-boarding

TBD

MOSIP can be configured to work with proxy implementation and multiple biometric modalities (fingerprint, iris and face). Below are configurations to enable biometrics in MOSIP.

Registration Client

Adding SDK in classpath

Biometric Windows SDK (jar file) should be placed in lib folder after extracting Registration-Client zip file, and then execute run.bat file.

Enabling MDS integration

The below property should updated to enable MDS integration. This property is present in file.

Registering biometric devices for registration

• Register Device Provider - Device Provider can be registered with MOSIP using

• Register MDS - MDS can be registered with MOSIP using

• Whitelist Device - Biometric Devices can be white-listed using below steps:

  • Add Device Specification (like model, make, etc.) using

  • Map Biometric Devices to Device Specifications using

  • Map White-listed Device to a Center ID to which Registration Client is tagged using

• Register Device - Biometric device can be registered using MOSIP using

Enabling biometric for officer and supervisor

Biometric authentication for officer and supervisor can be enabled by updating the is_active column to true in mosip_master.app_authentication_method table. List of processes for which biometric authentication can be enabled in registration client

• packet_auth (Authentication when packet is created)

• login_auth (Login to registration client)

• exception_auth (Authentication when an exception packet is created)

• eod_auth (Authentication for apporoving EOD packets)

By default, username password based authentication is enabled for all the above processes.

Enabling local de-duplication

Registration Processor

Configuring ABIS queue

ID Authentication

Adding SDK in classpath

Below properties should be set in id-authentication-{env}.properties. The classes configured below will be loaded in classpath during application initialization.

Registering biometric devices for authentication

• Update the code of the registered device to the serial number of the device in register_device_master and register_device_master_h table.

Encrypting biometric data from MDS

In order to capture encrypted biometrics from MDS, MDS should use Mosip Public Key. This key should be generated in MOSIP with IDA-FIR as reference-ID for Parter-based Individual Authentication and 'INTERNAL' as reference-ID for Internal Authentication.

The biometric devices that will be connected to MOSIP's registration machines to perform registrations need to be white-listed by the MOSIP administrator and registered by the device provider's management server.

White-listing of Devices

White-listing is an activity performed by the MOSIP administrator. As part of this activity, device details are stored in the MOSIP's master data and are mapped to various centers in the MOSIP ecosystem. To white-list a device the following steps are followed:

1. The device type should be available

2. The device specification should be available

3. The device should be created and mapped to a registration center

Adding Device Types

The device type is a master data which specifies the type of device. Ideally in case of biometrics devices, there would be only three types of devices, i.e. iris scanner, fingerprint slap scanner and a camera. This is an one-time activity that can be performed by the administrator for different types of devices.

The administrator should make sure that, the device type is available for a device, before creating any device specification. If the device type is not available then the administrator can create one.

API to Create a Device Type

** API Request Body **

POST https://{base_url}/v1/masterdata/devicetypes

{
  "id": "string",
  "metadata": {},
  "request": {
    "code": "Unique Code for Device Type",
    "description": "Description of the Device Type",
    "isActive": true,
    "langCode": "eng",
    "name": "Name of the Device Type"
  },
  "requesttime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "metadata": {},
  "response": {
    "code": "Unique Code for Device Type",
    "langCode": "eng"
  },
  "responsetime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

Note:

1. If you have MOSIP set-up with two language then you need to create this record twice with two different language codes.

2. The role for authentication of the API should be Global_Admin.

3. This needs to be created only if the device type is not available.

Adding Device Specification

The device specification is meta information about the device that the administrator want to use for registration. This contains basic details about the device like:

• Unique name of the device specification

• Brand name or make of the device

• Model of the device

• Device Type (from the device type created earlier)

• Driver version for the device (optional)

The administrator should make sure that, the specification is available for white-listing a device. If the device specification is not available then the administrator can create one.

API to Create a Device Specification

** API Request Body **

POST https://{base_url}/v1/masterdata/devicespecifications

{
  "id": "string",
  "metadata": {},
  "request": {
    "brand": "Brand or Model Name",
    "description": "Description of Device Specification",
    "deviceTypeCode": "Device Type Code from Device Type",
    "id": "Unique ID for Device Specification",
    "isActive": true,
    "langCode": "eng",
    "minDriverversion": "Driver Version of the Device",
    "model": "Model of the Device",
    "name": "Name of the Specification"
  },
  "requesttime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "metadata": {},
  "response": {
    "id": "Unique ID for Device Specification",
    "langCode": "eng"
  },
  "responsetime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

Note:

1. If you have MOSIP set-up with two language then you need to create this record twice with two different language codes.

2. The role for authentication of the API should be Global_Admin.

3. This needs to be created only if the device specification is not available.

Adding Device

After the device specification is available the administrator can white-list a device. Here, the administrator needs to capture the basic details about the device like,

• Serial number of the device

• IP Address of the device (optional)

• MAC Address of the device (optional)

• Validity of the device

• Administrative zone of the device

• Registration Center where the device will be used

API to Create a Device

** API Request Body **

POST https://{base_url}/v1/masterdata/devices

{
  "id": "string",
  "metadata": {},
  "request": {
    "deviceSpecId": "Specification ID from Device Specification",
    "id": "Unique ID for Device",
    "ipAddress": "IP Address of Device",
    "isActive": true,
    "langCode": "eng",
    "macAddress": "MAC Address of Device",
    "name": "Name of the Device",
    "regCenterId": "Mapped Center for the Device",
    "serialNum": "Serial Number of Device",
    "validityDateTime": "Validity Time for Device in format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "zoneCode": "Zone code for the device"
  },
  "requesttime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "metadata": {},
  "response": {
    "createdBy": "created by in DB",
    "deviceSpecId": "Device Specification ID",
    "id": "Unique ID for the device",
    "ipAddress": "IP Address of the Device",
    "isActive": true,
    "isDeleted": true,
    "langCode": "eng",
    "macAddress": "MAC Address of the Device",
    "name": "Name of the Device",
    "regCenterId": "Mapped Center ID",
    "serialNum": "Serial Number of the Device",
    "updatedBy": "updated by in DB",
    "validityDateTime": "Validity Time for Device in format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "zoneCode": "Mapped Zone Code"
  },
  "responsetime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

Note:

1. If you have MOSIP set-up with two language then you need to create this record twice with two different language codes.

2. The role for authentication of the API should be Global_Admin.

3. Make sure the center and device are mapped to same administrative zone.

Registering Devices in MOSIP

All the devices using which biometrics would be captured in MOSIP, need to be registered in MOSIP via. the management server before use. Before the management server makes a call to MOSIP for device registration various pre-requisites need to be performed,

• Policy group for device providers should be available

• Device provider should self-register in MOSIP as Partner using the Partner Management Portal

• Device provider must register the device make & model for which device registration request will reach MOSIP

• Request for device make & model should be approved by the Partner administrator

• Device provider must register the device's secure biometric interface

• Request for device's secure biometric interface should be approved by the Partner administrator

After the above mentioned steps, the device registration request can come from the device management server when the device is connected with the SBI.

Adding a Policy Group

A single policy group should be created for all the device vendors so that they can register into the MOSIP's partner management portal. Creation of policy group is an administrative activity which would be performed by the Policy administrator.

API to Create a Policy Group

** API Request Body **

POST https://{base_url}/partnermanagement/v1/policies/policies/policyGroup

{
  "id": "string",
  "metadata": {},
  "request": {
    "desc": "description of policy group",
    "name": "policy group name"
  },
  "requesttime": "2018-12-10T06:12:52.994Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "response": {
    "cr_by": "created by",
    "cr_dtimes": "2020-10-23T07:30:27.674Z",
    "desc": "description from request",
    "id": "unique ID",
    "is_Active": true,
    "name": "Policy Group Name from request",
    "up_by": "updated by",
    "upd_dtimes": "2020-10-23T07:30:27.674Z"
  },
  "responsetime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

Note:

1. The role for authentication of the API should be POLICYMANAGER.

2. This needs to be created if the policy is not available for device providers.

Registering Device Provider

The device provider needs to self register into the MOSIP system. During self registration we collect basic information from the partner, such as,

• Partner ID

• Organization Name

• Contact Number

• Postal Address

• Email Address

• Partner Type (for device providers its, Device_Provider which comes from the Master Data)

• Policy Group ID (from the policy group created earlier)

API to Create a Device Provider

** API Request Body **

POST https://{base_url}/partnermanagement/v1/partners/partners

{
  "id": "string",
  "metadata": {},
  "request": {
    "address": "Address of device provider",
    "contactNumber": "Contact Number of Device Provider",
    "emailId": "Email ID of Device Provider",
    "organizationName": "Organization Name of Device Provider",
    "partnerId": "Partner ID of the Device Provider",
    "partnerType": "Partner Type comes from Master Data for Device Providers - Device_Provider",
    "policyGroup": "Policy Group Name"
  },
  "requesttime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "metadata": {},
  "response": {
    "partnerId": "Partner ID set in Request",
    "status": "Active"
  },
  "responsetime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

Note:

1. The role for authentication of the API should be PARTNER.

2. This needs to be created if the partner is not available.

Registering Device's Make and Model

Once the device provider is approved, he/she needs to register his/her device's make and model information in the partner management portal. The make and model is basic device meta information that will be collected as part of device registration request. Here are the details that are captured as part of registering the device's make and model,

• Device provider's organization name and ID

• Brand Name or Make

• Model

• Device Type and Sub-Type (this is master data available in MOSIP for various types of devices)

API to Create a Device Make & Model

** API Request Body **

POST https://{base_url}/partnermanagement/v1/partners/devicedetail

{
  "id": "string",
  "metadata": {},
  "request": {
    "deviceProviderId": "Partner ID for the Device Provider",
    "deviceSubTypeCode": "Device Sub-Type Code comes from Device Type & Sub Type master Data",
    "deviceTypeCode": "Device Sub-Type Code comes from Device Type & Sub Type master Data",
    "id": "ID for the Device Details",
    "isItForRegistrationDevice": true,
    "make": "Make or Brand of the Device",
    "model": "Model of the Device",
    "partnerOrganizationName": "Organization Name of the Device Provider"
  },
  "requesttime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "metadata": {},
  "response": {
    "id": "ID for the Device Details"
  },
  "responsetime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

Note:

1. The role for authentication of the API should be DEVICE_PROVIDER.

2. This needs to be created if the device make and model is not listed earlier.

Approving Device's Make and Model Registration

The device's make and model details needs to be approved by the MOSIP's Partner administrator.

API to Approve a Device Make & Model

** API Request Body **

PATCH https://{base_url}/partnermanagement/v1/partners/devicedetail

{
  "id": "string",
  "metadata": {},
  "request": {
    "approvalStatus": "Activate",
    "id": "ID of the Device Details",
    "isItForRegistrationDevice": true
  },
  "requesttime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "ID of the Device Details",
  "metadata": {},
  "response": "string",
  "responsetime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

Note:

1. The role for authentication of the API should be PARTNER_ADMIN.

2. This needs to be done if the device make and model is pending approval.

Registering Device's Secure Biometric Interface (SBI)

Once the device's make and models are approved, the device provider needs to register his/her device's secure biometric interface in the partner management portal. The secure biometric interface is the software which would be interfacing with the devices and the registration client application. The below details would be collected when the device provider tries to register a SBI,

• Device details (from the device's make and model)

• Software creation time

• Software binary hash

• Software expiry time

• Software version

API to Approve a Device Make & Model

** API Request Body **

POST https://{base_url}/partnermanagement/v1/partners/securebiometricinterface

{
  "id": "string",
  "metadata": {},
  "request": {
    "deviceDetailId": "Device Details ID",
    "isItForRegistrationDevice": true,
    "swBinaryHash": "Hash of the SBI",
    "swCreateDateTime": "Creation date & time in the format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "swExpiryDateTime": "Expiry date & time in the format - yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "swVersion": "Software version number"
  },
  "requesttime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "metadata": {},
  "response": {
    "id": "Unique ID for the SBI"
  },
  "responsetime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

Note:

1. The role for authentication of the API should be DEVICE_PROVIDER.

2. This needs to be created if the device SBI is not registered.

Approving Device's Secure Biometric Interface Registration

The device's Secure Biometric Interface details needs to be approved by the MOSIP's Partner administrator.

API to Approve a Device Make & Model

** API Request Body **

PATCH https://{base_url}/partnermanagement/v1/partners/securebiometricinterface

{
  "id": "string",
  "metadata": {},
  "request": {
    "approvalStatus": "Activate",
    "id": "ID of the SBI",
    "isItForRegistrationDevice": true
  },
  "requesttime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "ID of the SBI",
  "metadata": {},
  "response": "string",
  "responsetime": "2020-10-23T07:30:27.674Z",
  "version": "string"
}

Note:

1. The role for authentication of the API should be PARTNER_ADMIN.

2. This needs to be done if the device SBI is pending approval.

Registering the Device

The devices would be registered in MOSIP by the Device Provider's Management server. The management server can send a device registration request using the device registration API provided by MOSIP. Details about the API is available here.

API to Register Devices in MOSIP

** API Request Body **

POST https://{base_url}/partnermanagement/v1/partners/registereddevices

{
  "id": "string",
  "metadata": {},
  "request": {
    "deviceData": { //The Device Data block is a JWT Toke signed using the Device Provider's Key
      "deviceId": "Unique ID coming from device",
      "purpose": "REGISTRATION",
      "deviceInfo": {  //The Device Info block is a JWT Token signed using Device Key
	  "deviceSubId": "Sub-ID of Device",
	  "certification": "Certification level of Device - L0",
	  "digitalId": { //The Digital ID block is a JWT Token signed using Device Key
	    "serialNo": "Serial Number in the Device",
	    "deviceProvider": "Device Provider Name",
	    "deviceProviderId": "Device Provider ID",
	    "make": "Brand or Make Name",
	    "model": "Model",
	    "dateTime": "2020-10-09T08:48:31.158Z", // Digital ID creation time (should be with in 5 mins when request is sent)
	    "type": "Device Type",
	    "deviceSubType": "Device Sub Type"
          },
	  "deviceExpiry": "2021-12-16T09:06:38.161Z",
	  "timestamp": "2020-10-09T08:48:31.158Z"
      },
      "foundationalTrustProviderId": ""
    }
  }
  "requesttime": "2020-10-09T08:48:31.158Z",
  "version": "string"
}

API Response Body

{
  "errors": null,
  "id": "string",
  "metadata": {},
  "response": { //The Response block is a JWT Token signed by MOSIP
    "status": "Registered",
    "digitalId":{ //The Digital ID block is a JWT Token signed using Device Key
	  "serialNo": "Serial Number in the Device",
	  "deviceProvider": "Device Provider Name",
	  "deviceProviderId": "Device Provider ID",
	  "make": "Brand or Make Name",
	  "model": "Model",
	  "dateTime": "2020-10-09T08:48:31.158Z",
	  "type": "Device Type",
	  "deviceSubType": "Device Sub Type"
    },
    "deviceCode": "unique device code for the device",
    "env": "Developer",
    "timestamp": "2020-10-06T07:01:30.374Z"
  },
  "responsetime": "2020-10-09T08:48:31.158Z",
  "version": "string"
}

Note:

1. This needs to be done if the device is not registered.

2. The Device Type & Device Sub Type Codes:

   1. Sub Types for Device Type "Finger" are "Slap", "Single" or "Touchless"

   2. Sub Types for Device Type "Iris" are "Single" or "Double"

   3. Sub Types for Device Type "Face" are "Full face"

3. Device Sub IDs for Finger/Iris is

   1. 1 - for left slap/iris

   2. 2 - for right slap/iris

   3. 3 - for two thumbs/irises

   4. 0 - if we don't know any specific device sub id

UI specification helps us identify how the data in an ID attribute (attributes of an ID object) is going to be retrieved from the UI. The UI screens in registration client application and pre-registration application are rendered using their respective UI specification JSON. We have different UI Specifications for Registration Client & Pre-registration which is derived from the ID Schema. Here we would be discussing about the properties used in the UI specification of Registration Client.

Registration Client UI Specification

Here is one of the attributes in the Registration Client UI Specification.

{
  "id": "fullName",
  "description": "Full Name",
  "label": {
    "primary": "Full Name",
    "secondary": "الاسم الكامل"
  },
  "type": "simpleType",
  "minimum": 0,
  "maximum": 0,
  "controlType": "textbox",
  "fieldType": "default",
  "format": "none",
  "fieldCategory": "pvt",
  "inputRequired": true,
  "validators": [
    {
      "type": "regex",
      "validator": "^(?=.{3,50}$).*",
      "arguments": []
    }
  ],
  "bioAttributes": null,
  "requiredOn": [],
  "subType": "name",
  "contactType": null,
  "group": "FullName",
  "required": true
}

UI Specification Properties

Below are the properties in registration client UI specification that are used to store ID attributes in an ID object.

ID

The id property is the unique id provided to a fields to uniquely identify it. The fields can be alpha-numeric without any spaces between them.

Description

This is a non-mandatory property used to describe the ID attribute.

Label

This property defines label name to be used in UI. The label has sub attributes as primary and secondary to store data in primary language and secondary language based on the country's configuration.

Type

This property defines the field value type for the attribute. MOSIP supports primitive as well as user defined types.

Currently MOSIP supports the below data types, any MOSIP adopter can choose to define their own data types.

• string

• number

• integer

• simpleType

• documentType

• biometricType

Below are the definitions of the user defined data types currently being used in MOSIP.

"definitions": {
  "simpleType": {
    "uniqueItems": true,
    "additionalItems": false,
    "type": "array
    "items": {
	  "additionalProperties": false,
	  "type": "object
	  "required": [
	    "language
	    "value"
	  ],
	  "properties": {
	    "language": {
		  "type": "string"
	    },
	    "value": {
		  "type": "string"
	    }
	  }
    }
  },
  "documentType": {
    "additionalProperties": false,
    "type": "object
    "properties": {
	  "format": {
	    "type": "string"
	  },
	  "type": {
	    "type": "string"
	  },
	  "value": {
	    "type": "string"
	  }
    }
  },
  "biometricsType": {
    "additionalProperties": false,
    "type": "object
    "properties": {
	  "format": {
	    "type": "string"
	  },
	  "version": {
	    "type": "number
	    "minimum": 0
	  },
	  "value": {
	    "type": "string"
	  }
    }
  }
}

Minimum

This property is applicable for only number fields to add UI level validation for minimum value.

Maximum

Similar to minimum, this property is applicable to only number fields to add UI level validation for maximum value. It is applicable only if the value is greater than zero.

Control Type

This property defines what kind of UI component to be used to capture data in UI. Currently the values that can be used are:

• textbox

• dropdown

• dob

• fileupload

Field Type

This property identifies if the ID attribute is country specific (specified as dynamic) or is already defined in the platform (specified as default).

Format

This property is used to add a simple validation in the UI level.

Currently, the allowed values here are

• lowercased - To validate if the data entered by the user is in lower case

• uppercased - To validate if the data entered by the user is in upper case

MOSIP adopter can choose to add more values for different types of validations.

Field Category

This property defines where the ID attributes will be placed in packet structure. Currently, the new packet structure has three parts; private, evidence and optional. For more details on packet structure please go through our documentation on Registration Packet.

Input Required

This is a mandatory property which decides if the input is to be provided from the UI or not. Items which are marked as true will be validated using the ID object validator.

Validator

This property enables us to add a the list of validators for the ID attribute. Each validator will have the below fields,

Currently, regex is supported by MOSIP, the adopter can choose to add various types of validators.

Bio Attributes

This property contains the list of biometric attributes that can be captured by the ID attributes which have type "biometricType".

• leftEye

• rightEye

• rightIndex

• rightLittle

• rightRing

• rightMiddle

• leftIndex

• leftLittle

• leftRing

• leftMiddle

• leftThumb

• rightThumb

• face

For various ID attribute there are different rules to capture biometrics,

• individualBiometrics - all the biometrics needs to be captured here if the resident is not an child

• individualAuthBiometrics - only one biometric is needed for authentication

• parentOrGuardianBiometrics - only one biometric is needed for authentication

Required On

This property contains a list of rules which decides if the attribute is mandatory or not. It has additional fields, engine and expr which are used to specify the rule engine and the expression.

Example for individualAuthBiometrics:

"requiredOn": [
  {
    "engine": "MVEL",
    "expr": "!identity.isChild && identity.isUpdate && !(identity.updatableFieldGroups contains 'Biometrics' || identity.updatableFieldGroups contains 'GuardianDetails')"
  }
]

This expression states that, individual biometric authentication capture is madatory when,

• the resident is not child

• the resident has come for update

• the resident is not updating his/her biometrics

• the guardian of the resident is not providing his/her biometrics

Which means, the applicant is an adult applicant who has come to the registration center to update only his/her demographics details, so we must capture his/her biometrics for authentication.

Sub type

This property helps the system to uniquely identify a attribute if we are not able to identify it using the type.

Example: In individualBiometrics, individualAuthBiometrics and parentOrGuardianBiometrics the types are same i.e. biometricType; hence to uniquely identify them we created sub types such as applicant, applicant-auth and introducer respectively.

Contact Type

This property is used to identify the contact attributes. Here we have categorized the contact types into three categories, i.e. email, phone and postal (all the postal address related items).

Group

This property is used to group the ID attributes so that we can select them in the update screen.

Examples:

• We have grouped all the address items as "Location", so that the resident needs to just select the group to update, i.e. the Location and in update screen he/she would be able to update all the location attributes.

• ID attributes related to Parent or Guardian are grouped together as "GuardianDetails".

Required

This is a mandatory property which is needed to identify if the ID attribute is mandatory or not.

Sample UI Specification

[
  {
    "id": "IDSchemaVersion",
    "description": "ID Schema Version",
    "label": {
      "primary": "IDSchemaVersion"
    },
    "type": "number",
    "minimum": 0,
    "maximum": 0,
    "controlType": null,
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "none",
    "inputRequired": false,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "IdSchemaVersion",
    "contactType": null,
    "group": null,
    "required": true
  },
  {
    "id": "UIN",
    "description": "UIN",
    "label": {
      "primary": "UIN"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "none",
    "inputRequired": false,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "UIN",
    "contactType": null,
    "group": null,
    "required": false
  },
  {
    "id": "fullName",
    "description": "Full Name",
    "label": {
      "primary": "Full Name",
      "secondary": "الاسم الكامل"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^(?=.{3,50}$).*",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "name",
    "contactType": null,
    "group": "FullName",
    "required": true
  },
  {
    "id": "dateOfBirth",
    "description": "dateOfBirth",
    "label": {
      "primary": "DOB",
      "secondary": "دوب"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "ageDate",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^(1869|18[7-9][0-9]|19[0-9][0-9]|20[0-9][0-9])/([0][1-9]|1[0-2])/([0][1-9]|[1-2][0-9]|3[01])$",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "identity.isNew || (identity.isUpdate && (identity.updatableFieldGroups contains 'GuardianDetails' || identity.updatableFieldGroups contains 'DateOfBirth'))"
      }
    ],
    "subType": "dateOfBirth",
    "contactType": null,
    "group": "DateOfBirth",
    "required": true
  },
  {
    "id": "gender",
    "description": "gender",
    "label": {
      "primary": "Gender",
      "secondary": "جنس"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "dropdown",
    "fieldType": "default",
    "format": "",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "Gender",
    "contactType": null,
    "group": "Gender",
    "required": true
  },
  {
    "id": "addressLine1",
    "description": "addressLine1",
    "label": {
      "primary": "AddressLine1",
      "secondary": "العنوان السطر 1"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^(?=.{3,50}$).*",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "addressLine1",
    "contactType": "Postal",
    "group": "Address",
    "required": true
  },
  {
    "id": "addressLine2",
    "description": "addressLine2",
    "label": {
      "primary": "AddressLine2",
      "secondary": "سطر العنوان 2"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^(?=.{3,50}$).*",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "addressLine2",
    "contactType": "Postal",
    "group": "Address",
    "required": false
  },
  {
    "id": "addressLine3",
    "description": "addressLine3",
    "label": {
      "primary": "AddressLine3",
      "secondary": "العنوانالخط 3"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^(?=.{3,50}$).*",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "addressLine3",
    "contactType": "Postal",
    "group": "Address",
    "required": false
  },
  {
    "id": "residenceStatus",
    "description": "residenceStatus",
    "label": {
      "primary": "Residence Status",
      "secondary": "حالة الإقامة"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "dropdown",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "residenceStatus",
    "contactType": null,
    "group": "ResidenceStatus",
    "required": false
  },
  {
    "id": "referenceIdentityNumber",
    "description": "referenceIdentityNumber",
    "label": {
      "primary": "Reference Identity Number",
      "secondary": "حالة الإقامة"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "kyc",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^([0-9]{10,30})$",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "none",
    "contactType": null,
    "group": "ReferenceIdentityNumber",
    "required": false
  },
  {
    "id": "region",
    "description": "region",
    "label": {
      "primary": "Region",
      "secondary": "منطقة"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "dropdown",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "Region",
    "contactType": "Postal",
    "group": "Location",
    "required": true
  },
  {
    "id": "province",
    "description": "province",
    "label": {
      "primary": "Province",
      "secondary": "المحافظة"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "dropdown",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "Province",
    "contactType": "Postal",
    "group": "Location",
    "required": true
  },
  {
    "id": "city",
    "description": "city",
    "label": {
      "primary": "City",
      "secondary": "مدينة"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "dropdown",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "City",
    "contactType": "Postal",
    "group": "Location",
    "required": true
  },
  {
    "id": "zone",
    "description": "zone",
    "label": {
      "primary": "Zone",
      "secondary": "منطقة"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "dropdown",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "Zone",
    "contactType": null,
    "group": "Location",
    "required": true
  },
  {
    "id": "postalCode",
    "description": "postalCode",
    "label": {
      "primary": "Postal Code",
      "secondary": "الكود البريدى"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "dropdown",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "Postal Code",
    "contactType": "Postal",
    "group": "Location",
    "required": true
  },
  {
    "id": "phone",
    "description": "phone",
    "label": {
      "primary": "Phone",
      "secondary": "هاتف"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^[+]*([0-9]{1})([0-9]{9})$",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "Phone",
    "contactType": "email",
    "group": "Phone",
    "required": true
  },
  {
    "id": "email",
    "description": "email",
    "label": {
      "primary": "Email",
      "secondary": "البريد الإلكتروني"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [
      {
        "type": "regex",
        "validator": "^[A-Za-z0-9_\\-]+(\\.[A-Za-z0-9_]+)*@[A-Za-z0-9_-]+(\\.[A-Za-z0-9_]+)*(\\.[a-zA-Z]{2,})$",
        "arguments": []
      }
    ],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "Email",
    "contactType": "email",
    "group": "Email",
    "required": true
  },
  {
    "id": "parentOrGuardianName",
    "description": "parentOrGuardianName",
    "label": {
      "primary": "Parent Name",
      "secondary": "اسم الوالدين"
    },
    "type": "simpleType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "evidence",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "( identity.isNew && identity.isChild ) || ( identity.isUpdate && identity.isChild )"
      }
    ],
    "subType": "parentOrGuardianName",
    "contactType": null,
    "group": "GuardianDetails",
    "required": false
  },
  {
    "id": "parentOrGuardianRID",
    "description": "parentOrGuardianRID",
    "label": {
      "primary": "Parent RID",
      "secondary": "الوالد RID"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "evidence",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "( identity.isChild && (identity.parentOrGuardianUIN == nil || identity.parentOrGuardianUIN == empty) )"
      }
    ],
    "subType": "RID",
    "contactType": null,
    "group": "GuardianDetails",
    "required": false
  },
  {
    "id": "parentOrGuardianUIN",
    "description": "parentOrGuardianUIN",
    "label": {
      "primary": "Parent UIN",
      "secondary": "الأصل UIN"
    },
    "type": "string",
    "minimum": 0,
    "maximum": 0,
    "controlType": "textbox",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "evidence",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "( identity.isChild && (identity.parentOrGuardianRID == nil || identity.parentOrGuardianRID == empty) )"
      }
    ],
    "subType": "UIN",
    "contactType": null,
    "group": "GuardianDetails",
    "required": false
  },
  {
    "id": "proofOfAddress",
    "description": "proofOfAddress",
    "label": {
      "primary": "Address Proof",
      "secondary": "إثبات العنوان"
    },
    "type": "documentType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "fileupload",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "identity.isNew || ( identity.isUpdate && (identity.updatableFields contains 'addressLine1' || identity.updatableFields contains 'addressLine2' || identity.updatableFields contains 'addressLine3'))"
      }
    ],
    "subType": "POA",
    "contactType": null,
    "group": "Documents",
    "required": false
  },
  {
    "id": "proofOfIdentity",
    "description": "proofOfIdentity",
    "label": {
      "primary": "Identity Proof",
      "secondary": "إثبات الهوية"
    },
    "type": "documentType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "fileupload",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "identity.isNew || ( identity.isUpdate && identity.updatableFields contains 'fullName')"
      }
    ],
    "subType": "POI",
    "contactType": null,
    "group": "Documents",
    "required": true
  },
  {
    "id": "proofOfRelationship",
    "description": "proofOfRelationship",
    "label": {
      "primary": "Relationship Proof",
      "secondary": "إثبات العلاقة"
    },
    "type": "documentType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "fileupload",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "( identity.isNew && identity.isChild ) || ( identity.isUpdate && (identity.updatableFieldGroups contains 'GuardianDetails' || identity.isChild))"
      }
    ],
    "subType": "POR",
    "contactType": null,
    "group": "Documents",
    "required": false
  },
  {
    "id": "proofOfDateOfBirth",
    "description": "proofOfDateOfBirth",
    "label": {
      "primary": "DOB Proof",
      "secondary": "دليل DOB"
    },
    "type": "documentType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "fileupload",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "identity.isUpdate && identity.updatableFields contains 'dateOfBirth'"
      }
    ],
    "subType": "POB",
    "contactType": null,
    "group": "Documents",
    "required": false
  },
  {
    "id": "proofOfException",
    "description": "proofOfException",
    "label": {
      "primary": "Exception Proof",
      "secondary": "إثبات الاستثناء"
    },
    "type": "documentType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "fileupload",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "evidence",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "POE",
    "contactType": null,
    "group": "Documents",
    "required": false
  },
  {
    "id": "proofOfException-1",
    "description": "proofOfException",
    "label": {
      "primary": "Exception Proof",
      "secondary": "إثبات الاستثناء 2"
    },
    "type": "documentType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "fileupload",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "evidence",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": null,
    "requiredOn": [],
    "subType": "POE",
    "contactType": null,
    "group": "Documents",
    "required": false
  },
  {
    "id": "individualBiometrics",
    "description": "",
    "label": {
      "primary": "Applicant Biometrics",
      "secondary": "القياسات الحيوية الفردية"
    },
    "type": "biometricsType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "biometrics",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": [
      "leftEye",
      "rightEye",
      "rightIndex",
      "rightLittle",
      "rightRing",
      "rightMiddle",
      "leftIndex",
      "leftLittle",
      "leftRing",
      "leftMiddle",
      "leftThumb",
      "rightThumb",
      "face"
    ],
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "(identity.isNew || identity.isLost || ( identity.isUpdate && identity.updatableFieldGroups contains 'Biometrics'))"
      }
    ],
    "subType": "applicant",
    "contactType": null,
    "group": "Biometrics",
    "required": true
  },
  {
    "id": "individualAuthBiometrics",
    "description": "Used to hold biometrics only for authentication",
    "label": {
      "primary": "Authentication Biometrics",
      "secondary": "القياسات الحيوية الفردية"
    },
    "type": "biometricsType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "biometrics",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": [
      "leftEye",
      "rightEye",
      "rightIndex",
      "rightLittle",
      "rightRing",
      "rightMiddle",
      "leftIndex",
      "leftLittle",
      "leftRing",
      "leftMiddle",
      "leftThumb",
      "rightThumb",
      "face"
    ],
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "!identity.isChild && identity.isUpdate && !(identity.updatableFieldGroups contains 'Biometrics' || identity.updatableFieldGroups contains 'GuardianDetails')"
      }
    ],
    "subType": "applicant-auth",
    "contactType": null,
    "group": null,
    "required": false
  },
  {
    "id": "parentOrGuardianBiometrics",
    "description": "",
    "label": {
      "primary": "Guardian Biometrics",
      "secondary": "القياسات الحيوية للوالدين"
    },
    "type": "biometricsType",
    "minimum": 0,
    "maximum": 0,
    "controlType": "biometrics",
    "fieldType": "default",
    "format": "none",
    "fieldCategory": "pvt",
    "inputRequired": true,
    "validators": [],
    "bioAttributes": [
      "leftEye",
      "rightEye",
      "rightIndex",
      "rightLittle",
      "rightRing",
      "rightMiddle",
      "leftIndex",
      "leftLittle",
      "leftRing",
      "leftMiddle",
      "leftThumb",
      "rightThumb",
      "face"
    ],
    "requiredOn": [
      {
        "engine": "MVEL",
        "expr": "(identity.isChild && identity.isNew) || (identity.isUpdate && identity.updatableFieldGroups contains 'GuardianDetails')"
      }
    ],
    "subType": "introducer",
    "contactType": null,
    "group": "Biometrics",
    "required": false
  }
]

The above attributes which are available in the current MOSIP platform, adopters can choose to add new attributes or remove attributes based on their requirement.

Steps to create your own UI specification

1. Create the basic ID Object definition & ID Schema as per your requirement.

2. If any of your attributes needs pre-defined master data (example: Blood Group)

   • The adopters can use our Dynamic Fields API to create dynamic master data

   • Then the adopter can add this field in the UI specification and mark the field type as dynamic

3. Once all the attributes are added, the adopter can create the UI Specification for registration client using the ID Schema APIs.

4. Once the UI Specification is created it needs to be published. Once published, the ID schema version is updated & an ID Schema is generated from the registration client UI specification for verification.

5. The adopters now can verify the structure of the ID schema derived against the one that they had defined earlier & make modifications as required.

6. Then the UI specification for Pre-registration needs to be created and should be updated in the file "pre-registration-demographic.json".

7. Once the file is placed the property "mosip.idschema.version" in pre-registration properties file should be updated to the latest ID schema version.

8. All the services needs to be re-started to use the new UI.