Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The MOSIP platform is configured via the Admin application. This application can be accessed only by a privileged group of administration personnel. The admin module provides the following functions:
Management of resources via CRUD operations:
Zone
Centers (registration centers)
Device
Machine
Users (Admin, registration staff)
Registration administration
Packet status
Retrieve lost RID
Resume RID
Administrative zones are virtual boundaries which a country can define to better manage their resources that are used during registrations. These resources includes Centers, Users, Machines and Devices. These zones can be defined in a hierarchical fashion and a country can allocate resources to such zones based on their requirements.
Resources under each zone is managed by a Zonal Admin. This is done by assigning an Administrative zone to the Zonal Admin during user creation.
These Zonal Admins can exist at any zonal hierarchy. (For e.g, a Zonal Admin can directly be mapped to the whole country as a Zone or can be mapped to a significantly smaller zone such as a city). Thus, these resources when mapped to an Administrative zone can only be managed by the Admin of that zone.
Deactivation refers to a reversible action in which the isActive value for a resource in database is set to "False". This means that the resource will not be available for use unless and until it is activated later through the admin portal as required by the country.
Decommission refers to a permanent/irreversible action of the resource. This also automatically deactivates it and the isDeleted value for the resource is set to "True".
The primary difference being that a decommissioned resource cannot be bought into commission again as decommission refers to a permanent shutdown.
Also, in cases where a center has some resources mapped to it (e.g. machines, devices or users), the portal will not allow the admin to decommission such a center.
Note- Activation/Deactivation/Decommission of a center in one language will be applied to the same center created in all the languages.
Reference implementation of the Admin portal is available in admin-ui repository.
To know more, refer to the Admin portal user guide.
To know more about the setup, read Admin Services Developer's Guide.
Refer API Documentation.
Admin application is a web-based application used by a privileged group of administrative personnel to manage various master data. The various resources that can be managed by an Admin are:
Center (Registration centers)
Device
Machine
Users (Admin, Registration staff)
Along with the resource and data management, the admin can generate master keys, check registration status, retrieve lost RID, resume processing of paused packets. To start using the Admin portal, an admin user must be assigned to a zone.
To learn more, refer the videos below!
Session1
Session2
Setup of hierarchial zones
Create Admin roles in KeyCloak
Create first admin user in KeyCloak and assign "GLOBAL_ADMIN" role
Note- On login of first admin user, user zone mapping is handled automatically.
The above are done automatically as part of default sandbox installation.
Select the preferred language.
Login with KeyCloak credentials.
Map the other users(admins/registration operators/supervisors) to respective zones
Create centers and assign the users to a particular center
Highly recommended: Ensure to revoke the first super user's zone mapping and role after first user actions are completed.
GLOBAL_ADMIN
ZONAL_ADMIN
REGISTRATION_ADMIN
MASTERDATA_ADMIN
KEY_MAKER
This portal allows an Admin to view, create, edit, activate, deactivate and decommission registration centers.
An Admin can manage only centers under their administrative zones.
The administrator can filter the list of registration centers based on parameters like Center name, Center type, Status, Location code.
The system does not fetch the details of decommissioned registration centers but only active and inactive centers are displayed.
If the admin does not find a center, they can click the Center not available in logged in language button. Clicking on this button, displays the list of centers that are already created in other languages. On selecting a particular center, the information will be auto-populated in the Create page and be made available to the admin for modifications.
Language specific fields can be modified to create a center with the currently logged in language.
A center is created with multiple attributes and is mapped to the administrative zone that it belongs to.
A center can only be mapped to the configured location hierarchy level.
While defining centers, an admin can also define the working days of the week for a center and any exceptional holidays that might be applicable for a particular center.
An admin can update a center even after it has been created. The updates can include adding the details that were missed during creation of the center or changing the details of a center as required.
To update, click the Edit option from the Actions menu against a center name.
Note- Updates made to language specific fields updates data only for that language in the database while updates made to non-language dependent fields updates data against all the language entries for that center.
Select the Deactivate/Decommission option from the Actions menu against the center.
Activation/Deactivation/Decommission of a center in one language will be applied to the same center created in all the languages.
To know more, refer Activate/deactivate/decommission resources
Using this portal, an admin can manage the devices a country will use for registering residents like devices used for bio-metric capture (Fingerprint, Iris, Web camera, etc.), printers, scanners.
This portal allows an Admin to view, create, edit, activate, deactivate and decommission registration centers.
The admin portal allows an admin to view the list of all the devices available in the jurisdiction of their administrative zone.
The system does not fetch the details of decommissioned devices but only the active and inactive devices.
Note
Device entity is language agnostic (independent of languages).
The data collected about Devices is used only for book keeping, i.e., MOSIP system does not use this data for any validation.
The Admin can filter the list of Registration centers based on parameters like Device Name, Mac Address, Serial Number, Status, Map Status, Device Type, Device Spec ID.
A Device can be created with the multiple attributes and be mapped to the Administrative Zone it belongs to.
An admin can update missing information or change device details even after it is created.
To update, click the Edit option from the Actions menu against a device.
Select the Deactivate/Decommission option from the Actions menu against the device.
Admin portal allows an Admin to map/un-map each device to a center.
This mapping specifies as to which center the device will be used in.
A device can only be mapped to a center which belongs under the device’s Administrative Zone.
To do so, select the device and choose a Center Name from the dropdowm.
Admin portal allows an administrator to manage the machines a country will use for registering residents.
This portal allows an Admin to view, create, edit, activate, deactivate and decommission machines.
The admin portal allows an admin to view the list of all the machines available in the jurisdiction of their administrative zone.
The system does not fetch the details of decommissioned machines but only shows the active and inactive machines.
Note:
Machine entity is also language agnostic.
The administrator can filter the list of machines based on parameters like Machine name, Mac address, Serial number, Status, Machine type.
A machine can be created with the attributes like Machine ID, machine name, mac address, serial number, machine spec ID and administrative zone the machine belongs to.
A machine needs to be mapped to an administrative zone.
An admin can update missing details or make changes to machine details even after it is created.
To update, click the Edit option from the Actions menu against a machine.
Note- Updates made to language specific fields updates data only for that language in the database while updates made to non-language dependent fileds updates data against all the language entries for that center.
An admin can deactivate or decommission a machine through the admin portal.
Admin portal allows an Admin to map/un-map each machine to a center.
This mapping specifies as to which center the machine will be used in.
A machine can only be mapped to a center which belongs under the machine’s Administrative Zone.
To do so, select the machine and choose a Center Name from the dropdowm.
MOSIP uses Keycloak as an IAM (Identity access management tool) for managing Users. These users are internal users of MOSIP including Registration Officers, Registration Supervisors, Zonal Admins, Global Admins etc.
using this portal, an Admin can map the users to a zone and a center.
Once the user is created in KeyCloak, they need to be mapped to a zone to get access to specific information available in that zone.
Admin portal allows an admin to map users to a zone. This mapping specifies as to which zone the user will belong to.
A user can only be mapped to a zone which belongs under the user’s Administrative Zone.
A user can later be un-mapped from the zone in case a user needs to be moved to another zone. In such cases, the user will later need to be mapped to the new zone. Below image displays the list of users that are mapped to a zone.
Click Resources-> User Zone mapping
Click +Map Zone
Select the User Name, Administrative Zone from the dropdown.
Click Save.
To re-map a user to a zone,
Click Resources-> User Zone mapping
Select Remap from the Actions menu against the mapped user.
Update the User Name/ Administrative Zone from the dropdown.
Click Save.
Note- If the center is already mapped, the admin needs to unmap the center to remap the zone.
Once the user is mapped to a zone, they will be listed in the screen below. Now, the user will be mapped to a center to be able to manage their assigned center.
Admin portal allows an admin to map users to a center. This mapping specifies as to which center the user will be used in.
A user can only be mapped to a center which belongs under the user’s Administrative Zone.
A user can later be un-mapped from the Center in cases where a User is needed to be moved to another Center. In such cases, the user will later need to be mapped to the new center. In case the user is required to be mapped to a Registration center outside the Administrative Zonal restriction, the Administrative Zone of the user must be changed.
Map/un-map/re-map user to a registration center
To map a user to a center,
Click Resources-> User Center Mapping
Select Map from the Actions menu against the mapped user.
Select the Center Name from the dropdown against the User Name, Administrative Zone.
Click Save.
To get the results starting with specific character/ set of characters, prepend that specific character/set of characters with asterisk
symbol.
Similarly to get the results ending with specific character/ set of characters, append that specific character/ set of characters with asterisk
.
For the results containing a specific character/ set of characters, prepend and append that specific character/ set of characters with asterisk
.
Below is the image illustrating the same.
A Registration packet generated in Registration client is sent to Registration Processor for further processing and UIN generation.
Using this Portal, A Registration Admin can view the status of a packet by entering the RID of the packet.
The packet status will contain all the stages the packet has passed through along with the last stage the packet is in.
In case the packet has not been processed or is marked for Re-Send/Re-Register, the admin will be able to view specific comments indicating the reason for that particular status.
The Registration Admin has the privilege to view the registration packets that are in a paused state.
Admin can use this portal to resume or reject paused packets. They would have 3 options:
Resume processing (from where it was paused)
Resume from the beginning
Reject
Once processing of a packet is resumed, it will be removed from this list
The Registration Admin can use this feature to retrieve lost RID.
For instance, if the resident did not provide any valid email and/or phone number and has lost the RID slip received during the registration, in order to find their RID details, the resident contact MOSIP helpline and share details such as name, centre name, registration date and postal code to the admin, who will use the lost RID feature and try to retrieve the RID number.
A few filters may be applied to retrieve the RID.
Note: This feature is currently under development.
Admin portal allows an Admin to manage the Masterdata applicable for a country.
These data includes list of Genders, list of Holidays, Templates, Center Types, Machine Types etc.
To know more, refer to Masterdata guide.
If a country decides to uplaod the data through the .csv files, they could use this feature to upload the existing data into the MOSIP platform.
The listing screen displays the uploaded data transaction information.
As the information inside .csv files may be huge, it would go through the batch job to process the information and store it in the tables. Also, it may take time to get unique transaction ID against the particular action.
To upload Master data using Admin portal,
Go to Bulk Upload > Master Data
On the master data dashboard, click Upload Data.
Select the operation (insert/update/delete)
Select the table name into which the data needs to be uploaded into.
Click Choose file to select the data and click Upload
To view the format for inserting data in a particular table, click on the Download icon.
A CSV file gets downloaded in which the first row represents the column names and the rest of the rows are the data which will be inserted into the table(sample).
From 1.2.0.1-B2 version, apart from comma, other special characters (i.e., '|','$'etc.) can also be used as a separator in the csv file used for masterdata bulk upload. This can be done by updating the property mosip.admin.batch.line.delimiter
with the same special character.
Note: While editing CSV files, it is recommended to keep track of the Date format and Time format to be the same as the acceptable formats. The acceptable Date format is YYYY-MM-DD and the acceptable Time format is HH:MM:SS. Any other Date and Time formats in CSV files will result in a DataType Mismatch Error
.
To upload packets using Admin portal,
Go to Bulk Upload > Packets
On the packet upload dashboard, click Upload Packet.
Select the following from the dropdown:
Center name
Source (currently displays Registration Client)
Process (New, Update UIN, Lost, Biometric correction)
Supervisor status (Approved/Rejected)
These details are important if the packet needs to be synced before upload.
Click Choose file to select the packets and click Upload.
How is the packet upload performed with or without DATA_READ role?
For uploading the packets through the Admin portal, ensure that the packets are available in the machine or the external hard disk connected from where the Admin Portal is being used.
With the help of this feature, the Admin user can generate and manage the keys required in MOSIP.
The logged in user with KEY_MAKER
role will have access to view and generate the master key in the Admin portal.
Using this option, the logged in user will be able to generate only the Root key and Module master key. To generate the key, the user has to select the Application ID from the options available in the drop down, leave the Reference ID as blank for Root and Module master key and provide other certificate attributes to be used at the time of generation of certificate for the key.
This certificate attributes in the portal are optional, if not provided, default values configured in Key Manager service will be used.
For Kernel signature key (which is considered as the master key and stored in HSM), Reference ID needs to be provided and the value has to be SIGN
.
Force flag option is available in key generation. The logged in user can select option value True to force invalidating existing key and generate new key in Key Manager service.
The logged in user has to select the return object after the generation of key.
The user can select either Certificate or CSR (Certificate Signing Request). The key will be generated only when the key is not available in Key Manager service otherwise already generated key certificate will be returned for the generation request.
CSR (certificate signing request) is required when there is a need to procure a valid certificate from a valid CA.
GenerateCSR option can be used to request for a CSR and this option will be visible to all the users who log in to the Admin portal.
The logged in user can request for generation of CSR for any key generated in Key Manager service.
The user has to provide the Application ID and Reference ID to get a CSR.
New key will be auto-generated in case the key does not exist and the already existing key has expired for the Module Encryption keys.
The user can get certificate for all the keys generated in Keymanager and any partner certificates uploaded in Keymanager service for partner data share purpose.
GetCertificate option is visible to all the users who log in to the Admin portal.
The user has to provide the Application ID and Reference ID to get a certificate.
New key will be auto generated in case the key does not exist and the already existing key has expired for Module encryption keys.
Only current valid certificates will be returned when the user requests for a certificate.
The logged in user can use this option to update the certificate for all the keys generated in Key Manager service.
This option is used in scenarios where a valid CA certificate has been procured for a key available in Key Manager service.
The logged in use can use this option to upload partner certificate in Key Manager service.
Partner certificates will be used in Key Manager service to encrypt any sharable data using the partner certificate required in datashare from MOSIP to any partner.
Partner certificates can also be used in Key Manager service for signature verification purpose.
The admin application is a web-based application used by a privileged group of administrative personnel to manage various master data. The various resources that can be managed by an administrator are:
Center (Registration centers)
Device
Machine
User (Admin, Registration staff)
Along with resource and data management, the admin can generate master keys, check registration status, retrieve lost RIDs, and resume processing of paused packets.
Masterdata Service exposes API to perform CRUD operations on masterdata through Admin service.
Hotlist Service provides functionality to block/unblock any IDs with option of expiry. This hotlisted information will also be published to MOSIP_HOTLIST WebSub topic.
Sync Data Service can be accessed only by the privileged group of admin personnel and enables default configurations and seed data to be setup when the MOSIP platform gets initialized.
The admin module has four services:
Admin service
Kernel Masterdata service
Kernel Syncdata service
Hotlist service
The documentation here will guide you through the pre-requisites required for the developer' setup.
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git/GitHub Desktop
Notepad++ (optional)
lombok.jar (file)
settings.xml
Follow the steps below to set up Admin Services on your local system:
Download lombok.jar and settings.xml.
Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to conf
folder C:\Program Files\apache-maven-3.8.4\conf
.
Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/ Update
.
Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
For the code setup, clone admin-services repository and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
Clone admin-services repository.
Any changes in the properties for Masterdata and Admin services should be done in application-local1.properties
file.
By default the Admin-services is connected to dev environment.
To run the specific service from IDE, Open IDE -> Specific service -> src/main/java/io.mosip.specific service -> Right click on the file and select run as Java Application
.
For example, to run the Admin service, open IDE -> admin-service -> src/main/java/io.mosip.admin -> Right click on AdminBootApplication.java and select run as Java Application
.
To run the specific service from Command Prompt, Open Project folder -> open command prompt from same folder -> Execute java -jar target/specific-service-1.2.0.jar
.
For example, to run the admin service, Open Project folder -> open command prompt from same folder -> Execute java -jar target/admin-service-1.2.0-SNAPSHOT.jar
.
The service should now be up and running.
For API documentation, refer here.
The APIs can be tested with the help of Swagger-UI and Postman.
Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of admin-services for dev-environment from:
Admin service– http://dev.mosip.net/v1/admin/swagger-ui/index.html?configUrl=/v1/admin/v3/api-docs/swagger-config#/
and localhost from http://localhost:8098/v1/admin/swagger-ui/index.html?configUrl=/v1/admin/v3/api-docs/swagger-config#/
.
Masterdata- http://dev.mosip.net/v1/masterdata/swagger-ui/index.html?configUrl=/v1/masterdata/v3/api-docs/swagger-config#/
and localhost from http://localhost:8086/v1/masterdata/swagger-ui/index.html?configUrl=/v1/masterdata/v3/api-docs/swagger-config#/
.
Syncdata- http://dev.mosip.net/v1/syncdata/swagger-ui/index.html?configUrl=/v1/syncdata/v3/api-docs/swagger-config#/
and localhost from http://localhost:8089/v1/syncdata/swagger-ui/index.html?configUrl=/v1/syncdata/v3/api-docs/swagger-config#/
.
Hotlist- http://dev.mosip.net/v1/hotlist/swagger-ui/index.html?configUrl=/v1/hotlist/v3/api-docs/swagger-config#/
and localhost from http://localhost:8095/v1/hotlist/swagger-ui/index.html?configUrl=/v1/hotlist/v3/api-docs/swagger-config#/
Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster. It is widely used tool for API testing.
Create an environment as shown in the image below.
This environment is created for dev. Give the variable name as url
and set both the values as https://dev.mosip.net
.
In the similar way, create another environment for localhost as shown below.
This environment is created for localhost. Give the variable name as url
and set both the values as http://localhost:8099
.
GLOBAL_ADMIN | ZONAL_ADMIN | REGISTRATION_ADMIN | MASTERDATA_ADMIN | KEY_MAKER |
---|---|---|---|---|
To map a user to a zone,
LoggedIn User Role | Packet Sync | Packet Upload |
---|---|---|
Centers
Devices
Packet Status
Devices
GenerateMasterKey
User Zone Mapping
Machines
Pause/ Resume RID
Machines
GenerateCSR
All Master Data
User Zone Mapping
Retrieve Lost RID
All Master Data
GetCertificate
Masterdata Bulk Upload
User Center Mapping
Packet Bulk Upload
Masterdata Bulk Upload
UploadCertificate
All Master Data
UploadOtherDomainCertificate
Masterdata Bulk Upload
With DATA_READ
Yes
only after successful sync
Without DATA_READ
No
Yes
This guide provides a comprehensive list of configurable properties for the Android Registration Client. Please note that this list is not exhaustive but serves as a helpful checklist for reviewing commonly configured properties.
It is important to acknowledge that all properties listed in this guide are automatically synchronized with the Android Registration Client. These properties are sourced from the registration-default.properties
file.
application-default.properties
registration-default.properties
Timeouts in milliseconds set during any http calls to SBI.
Quality score threshold based on modality, Possible values 1 to 100
Retry attemps, Possible values 1 to 10
Quality score threshold based on modality for operator authentication, Possible values 1 to 100`
Jobs like RID sync, packet upload, status sync is carried out in batches, number of registration records to be executed in a batch on every trigger.
Default CRON expression for scheduling the Jobs.
mosip.registration.sync_jobs_restart_freq=0 0 */11 ? * *
Enables / disables reviewer authentication on any biometric exception during registration
mosip.registration.reviewer_authentication_configuration=Y
If enabled, cross-checks of residents biometrics with locally stored operator biometric templates.
mosip.registration.mds.deduplication.enable.flag=N
Minimum disk space required to create a packet - in MB
mosip.registration.disk_space_size=5
Maximum no. of days for approved packet pending to be synced to server beyond which Registration Client is frozen for registration
mosip.registration.last_export_registration_config_time=100
No. of days beyond audit creation date to delete audits
mosip.registration.audit_log_deletion_configured_days=10
Maximum duration to which registration is permitted without sync of master data
mosip.registration.sync_transaction_no_of_days_limit=5
Allowed number of invalid login attempts
mosip.registration.invalid_login_count=50
Configuration used to check if any sync job is missed/ failed beyond expected days, this configuration is checked everytime operator clicks on any registration process. We follow below convention to create this config key.
mosip.registration.job api name as in sync_job_def table.frequency=value in days
Date format to be displayed on acknowledgement slip, default value - dd/MM/yyyy hh:mm a
mosip.registration.application_date_format
Date format to be displayed on Registration Client dashboard, default format - dd MMM hh:mm a
mosip.registration.dashboard_date_format
Due to the absence of UI specifications in the 1.1.5.x versions, the android regclient addresses backward compatibility by migrating the schema of these versions to the LTS UI Spec structure.
In order to facilitate this migration, certain configurations and templates have been incorporated to ensure compatibility with the 1.1.5.x server. The list of these configurations is provided below.
mosip.registration.consent-screen-template-name=reg-consent-screen-content-template
Consent screen is not a part of 1.1.5.x schema structure. So, we are completely fetching this consent screen content from master.template
table, and the templateTypeCode
for the consent screen content is mentioned in the above configuration.
mosip.registration.individual-biometrics-id=individualBiometrics
The id of individual biometrics should be mentioned in the above property according to the configured 1.1.5.x schema.
mosip.registration.introducer-biometrics-id=guardianBiometrics
The id of guardian/ introducer biometrics should be mentioned in the above property according to the configured 1.1.5.x schema.
mosip.registration.infant-agegroup-name=INFANT
The age-group name for infants (aged below 5 years) which is configured in the configured server should be mentioned in the above property.
mosip.registration.agegroup-config={"INFANT":{"bioAttributes":["face"],"isGuardianAuthRequired":true},"ADULT":{"bioAttributes":["leftEye","rightEye","rightIndex","rightLittle","rightRing","rightMiddle","leftIndex","leftLittle","leftRing","leftMiddle","leftThumb","rightThumb","face"],"isGuardianAuthRequired":false},"SENIOR_CITIZEN":{"bioAttributes":["leftEye","rightEye","rightIndex","rightLittle","rightRing","rightMiddle","leftIndex","leftLittle","leftRing","leftMiddle","leftThumb","rightThumb","face"],"isGuardianAuthRequired":false}}
The above property indicates list of age-groups, required bio-attributes, and a flag which indicates guardian authentication is required or not. This property should be changed according to the server configuration and requirements.
mosip.registration.allowed-bioattributes=leftEye,rightEye,rightIndex,rightLittle,rightRing,rightMiddle,leftIndex,leftLittle,leftRing,leftMiddle,leftThumb,rightThumb,face
The above property defines the list of bio-attributes that are allowed for scanning during registration. If there are any changes in the server, it should be changed accordingly.
mosip.registration.default-app-type-code=000
The above property defines the default applicantTypeCode. In LTS, we have applicanttype.mvel script to fetch the documents according to the age, gender and some other attributes. Based on the applicant details, the script returns an applicantTypeCode which can be any value from “000” to “014”, and respective documents will be fetched from master.applicant_valid_document table
. Since we do not have this script defined in 1.1.5.x to handle this, we have added a default applicantTypeCode
.
Ensure that the preview and acknowledge templates are present in the template table
of mosip_master
database with the following type code:
reg-android-preview-template-part
reg-ack-template-part
The documentation here will guide you through the pre-requisites and the other necessary details required for Android Registration Client developer setup.
The android-registration-client repository contains the Android Registration Client software for MOSIP. The feature-flutter branch focuses on integrating Flutter into the client.
To set up the Android Registration Client with Flutter and Android Studio, follow the steps below:
Flutter SDK (3.10.4): Install Flutter by following the official Flutter installation guide.
Android Studio (or Any IDE of your choice): Download and install Android Studio from the official Android Studio website.
The develop
branch of android-reg-client is currently being actively developed. If you wish to access this branch, you can clone the repository by executing the following command in your terminal. Alternatively, you can download one of the releases available in the repository's release section.
Active Branches:
release-0.9.x(developer release branch)
develop(active development branch)
To begin, launch Android Studio.
Next, select Open an existing Android Studio project and navigate to the cloned repository.
Open the android-registration-client
directory as a project in Android Studio.
In order to integrate Flutter with Android Studio, install the Flutter plugin by accessing File > Settings > Plugins
and searching for Flutter. Proceed to click on Install to install the plugin.
To ensure proper functionality, configure the Flutter SDK path by navigating to File > Settings > Languages & Frameworks > Flutter
and specifying the Flutter SDK path as the location where you have installed Flutter.
Finally, save the changes by clicking on the "Apply" button.
Customising the Registration Client
Styling of the application can be configured by modifying these files lib/utils/app_style.dart, lib/utils/app_config.dart
Application language bundles can be added to this path lib/l10n
.
Label and application logo can be changed here android/app/src/main/AndroidManifest.xml
The pigeon.sh
file consists of the necessary commands for downloading dependencies and generating Flutter - Android native communication code. Please execute the pigeon.sh
file or execute the commands within the file separately.
Ensure you have connected an Android device or initiated an Android emulator.
Open the terminal within Android Studio or use an external terminal.
Navigate to the android-registration-client
directory.
Run the following command in order to build and execute the application:
Excecute the commands below to debug and release the APK
The Mock MDS tool can be utilized to simulate the functionalities of biometric devices. The Mock MDS application is compliant with CTK standards and can serve as a substitute for Android SBI modules during testing and validation.
Install the Mock MDS application.
Access the Settings menu.
Under Device Configuration, choose Registration from the dropdown menu.
In P12 Configuration:
Enter the necessary credentials for the Device Key and upload the Device P12 file.
Enter the required credentials for the FTM Key and upload the FTM P12 file.
Complete all fields in MOSIP IDA Configuration.
In Modality Configuration, specify the quality score for Face, Finger, and Iris scans(these values can also be adjusted during testing).
Click on the Save button.
Go back to the Home Page and select LOAD AND VALIDATE CERTIFICATES
.
A toast message will be displayed indicating the success of the validation process.
Note: To view the released version of the Mock SBI APK, click here.
To download the Mock SBI APK, click on camera-mds.zip
.
If you would like to contribute to the Android Registration Client, please follow the guidelines outlined here.
The Android Registration Client is licensed under the MIT License.
If you encounter any issues or have any questions, please open an issue on the GitHub repository.
GitHub- mosip/android-registration-client: Reference Android Registration Client Software - WIP
The Android Registration Client is a tablet application that serves as a portable version of the existing desktop Registration Client. It has been developed to support accessibility on all Android devices. The existance of Android Registration Client came about in order to meet the mobility requirements of countries adopting MOSIP.
The primary objective of the tablet version is to facilitate the registration process for residents, specifically those who are unable to physically visit registration centres and also serve remote locations where setting up Registration centres is not feasible. To address this challenge, the Android Registration Client was created, enabling Operators/ Supervisors to easily reach the remote areas and maximise resident registrations across the country.
To have a quick glance at the features, refer the video below!
The first developer release of Android Registration Client offers the following key features:
Operator/ Supervisor Login (offline and online): Operators can securely log in using their credentials, whether in offline or online mode, to carry out various registration transactions. To enable offline login, the Operator must have previously logged in and synchronized their data over a network.
Multi-language support: The Android Registration Client supports multiple languages for content display and data entry.
Display Language: Display Language refers to the language used for rendering UI elements such as labels and headings. With the Android Registration Client, Operators have the option to choose their preferred language for UI display. This language selection can be made on the login screen. Currently, the supported display languages include Arabic, French, English.
New languages can be added by following the below steps:
i. Additional languages can be configured by adding localisation files in lib/l10n
folder present in the root project directory("android_registration_client").
ii. The languages that are rendered on the UI will be based on the country configuration (after master data sync). The default display language is English. The other languages will be available in the UI after master data sync.
To know more, refer Flutter doc-Internationalizing Flutter apps.
Data Entry Language: The Data Entry Language refers to the specific language utilized by the Operator while gathering data, which is then stored on the server in that selected language. During the registration process, the Operator can choose the language preference for the data collected, allowing applicants to provide information in their desired language. This language selection option becomes available upon initiating a new registration. The responsibility for managing the data entry language lies within the UI Spec, and any modifications or changes can be made through that specification.
Auto-Sync/ manual sync: On launching the Android Registration Client and logging in for the first time, the system automatically syncs the following data:
Configuration sync: Sync of properties which drives in deciding the ARC UI functionality. For example: Invalid login attempts, idle timeout, thresholds, etc.
Masterdata sync: As a part of this sync, supporting information like Dynamic fields data, templates, locations, screen authorization, blocklisted words, etc. are pulled in.
UserDetails sync: userID, along with their status is synced. Only the user details belonging to machine mapped center will be synced.
Certificate sync: Certificates used to validate the server signatures, device CA certificates, public key (specific to a center and machine, also called as policy key) used to encrypt the registration packet will be synced.
New Registrations : Operators have the ability to register a resident using the New Registration
feature. The registration process can be customized through the UI specification. The required data for registering an applicant are as follows:
Consent: Prior to the registration process, applicants must provide consent to the terms and conditions presented on the consent screen. This explicitly asks the applicant to grant permission for storing and using their Personally Identifiable Information (PII).
Demographic Details: Once the consent is obtained, the Operator will enter the demographic data of the applicant in the language preferred by the applicant. This includes details such as their name, gender, date of birth, and residential address.
Documents Upload: Following the completion of the demographic details, the Operator can select the document type, input the reference, and upload the supporting documents provided by the applicant. Supporting documents may include Proof of Address, Proof of Identity, and Proof of Birth, based on the country-specific requirements.
Biometrics: After the documents have been uploaded, the Operator will proceed to capture the applicant's biometrics. The biometrics captured are as follows:
The acquisition of biometric data is regulated by the country. The country has control over the capture of each type of biometric (fingerprint, iris, or face) through the global configuration. When the Operator selects the Capture button, the biometric SBI application is accessed to capture the biometrics. Once the biometrics are obtained, the data and control are returned to the Android Registration Client. To obtain the resident's biometrics, the quality of the captured image must exceed the threshold specified by the country. The biometrics can be captured set number of times if necessary to meet the quality threshold. In situations where none of the captured images meet the threshold, the image with the highest quality score will be saved.
If the resident has a biometric exception (such as a missing finger/eye or very poor finger/iris quality), the Operator can designate that particular biometric as an exception. However, the Operator must still capture the resident's exception photo.
Preview section: The Operator has the ability to review the data entered by the applicant, including demographic information, uploaded documents, and captured biometrics. This preview allows the Operator to ensure the accuracy of the entered data. If any mistakes are found, the Operator can easily go back to the corresponding section and make the necessary corrections. If the data is correct, the Operator can proceed to the next step, which is to authenticate themselves.
Operator authentication: Once both the Operator and applicant have confirmed that the data is accurately filled, the Operator is required to authenticate themselves using their credentials. After a successful authentication, the data packets are created and only then the sync and upload operations can be performed.
Packet sync: After the applicant's registration form has been completed and the Operator has authenticated themselves, a packet sync must be performed. This can be done either manually or as a background job(auto sync and uplaod of packets). Packet sync ensures that the packet is prepared for uploading and the status of the uploaded packet is synchronized with the server.
Packet Upload: Once the packet sync is successfully completed, the system will proceed to upload the packet to the server when an internet connection is available. If there is no network access, the system will attempt to upload the packet as soon as connectivity is established.
Acknowledgment section: Following the completion of the new registration process, an acknowledgment receipt is generated. This receipt includes the AID(Application ID), captured demographic data in the selected language, a photograph of the resident, and a ranking of each finger from 1 to 10, with 1 representing the finger with the best quality. The receipt is designed to be easily printed.
To read through the comprehensive list of configurable properties for the Android Registration Client, refer Android Registration Client Configuration Guide.
For more details on UI specifications for the Android Registration Client, refer here.
The Android Registration Client is compatible with the following MOSIP platform versions:
1.1.5.x
LTS 1.2.0 and above
This user guide is designed to provide assistance to Operators and Supervisors in successfully installing, running, and registering applicants to obtain their Unique Identification Numbers (UIN) on tablet devices.
Reliable and consistent Internet connectivity.
Tablets running Android version 10 to 13.
Tablets with a minimum of 4 GB RAM.
The tablets need to be capable of capturing fingerprints, iris, and face (photo) biometrics. Additionally, they should also have the ability to scan documents. However, if the tablets do not support these capabilities, MOCK SBI can be used as an alternative.
Download and install the APK on Android tablet.
Once ARC is installed, long press on the logo to copy the machine details.
On the Admin Portal, using admin credentials, login and perform the following to add the device:
Go to Resources/Machine
and click on Create machine
Add a new machine and enter the machine details:
Add the specs as Mobile
Map it to a Zone and Center
Add the Machine spec ID as Mobile
Enter Device name
Enter Public Key
Enter Sign Public Key
Create the role Default
in KeyCloak with all the other roles.
Create the Operator’s user account in KeyCloak and set the password and assign the role as Default
, REGISTRATION_OFFICER
, Registration Operator
, REGISTRATION_SUPERVISOR
Login into Admin Portal to perform the following and add the user:
After login into Admin Portal, go to User Zone Mapping
and add the zone for the user and activate the zone.
Go to User Center Mapping
and add the center for the user and activate it.
Note: The user should be assigned to the same Zone and Center as the device.
The user should relaunch the ARC and log in using their valid credentials. Additionally, the operator has the option to select their preferred display language.
Upon successful login, the user will be directed to the Home page, which includes the following options:
New Registration
Operations Tasks (Future scope)
Dashboard (Future scope)
Settings (Future scope)
To begin the Registration process, the Operator is required to follow the steps outlined below.
Click on New Registration card.
Select the language to be used for data entry, which will be used to collect the resident's information. There will be a default language for data entry.
Choose the language in which the notification will be sent to the resident. Click Submit to proceed.
The operator will be redirected to the Consent page, where the resident must agree to the terms and conditions
in order to proceed.
After accepting consent, the Operator will need to fill out the demographic data of the resident, including their name, age, date of birth, and address. Once all mandatory fields are completed, the Continue button will be enabled.
Upon clicking the Continue button, the Operator will be navigated to the Document upload
page where they will need to:
Select the type of document (e.g. proof of identity, proof of address) from the drop-down menu.
Enter the Reference Number of the document.
Upload the document by clicking on the Scan button to open the camera. The Operator can take a picture of the document and then choose from the following actions:
Cancel: Clicking on the "Cross" icon will remove the captured image and return the Operator to the previous screen.
Crop: The Operator can drag from the four corners of the captured image to crop it as needed.
Save: Clicking on the "Save" button will save the captured image and return the Operator to the previous Document Upload page.
Retake: Clicking on the "Retake" button will remove the captured image, reopen the camera, and allow the Operator to take a new photo.
After ensuring all required information has been accurately entered in the Document Upload
screen, the Operator can proceed by clicking on the Continue button to access the Biometric Capture
page. Here, the Operator can capture the biometric data of the Resident, including a face photo, fingerprint, and iris scan.
Face photo capture process
For capturing the face photo, the Operator should click on the Scan button to activate the camera and take a picture.
The image quality will be displayed on the screen and must meet a certain threshold to be considered acceptable.
The Operator has three attempts to capture the biometric image.
It is important to note that no exceptions can be made for the face photo biometric capture process.
Biometric Data capture process:
In order to capture biometric data, the Operator should click on the Scan button.
This will allow the Operator to capture the biometric information.
Once the data is captured, the image quality will be displayed on the screen and must meet the acceptable threshold limit.
Note: Three attempts are provided to capture the biometric data.
Fingerprint Capture Process:
In the event that a thumb is missing or experiencing difficulties that prevent its fingerprint from being captured, the Operator is authorized to indicate an exception. To mark an exception, the operator must select the affected thumb and specify the type of exception as either Temporary or Permanent. Additionally, the operator may include any relevant additional comments.
Iris Scanning Process:
To initiate the Iris scan, the Operator is required to click on the Scan button.
This action will allow the Operator to capture the Iris image.
Once the Iris has been successfully captured, the quality of the image will be displayed on the screen.
It is essential for the quality score to meet the established threshold limit.
The Operator has three opportunities to capture the biometric data.
If one or both of the Irises are not detected or encounter issues that prevent successful capture, the Operator has the option to mark an exception. To do so, the Operator must identify the specific Iris that is problematic and indicate the type of exception- either Temporary or Permanent. Additionally, the Operator may provide any relevant comments.
After all the biometric data has been properly captured or any exceptions have been noted, the Continue button will be activated. The Operator can then proceed by clicking on the Continue button, which will redirect them to the Preview page. The Preview page will display the following information:
Application ID
Timestamp of Registration
Demographic data collected
Documents submitted
Biometric data recorded
From the Preview page, the Operator has the ability to navigate back to previous screens in order to make any necessary adjustments to the entered or captured data. Once the Operator has verified the accuracy of the entered data, they can proceed by clicking on the Continue button, which will direct them to the Operator Authentication
page.
On the Operator Authentication
page, operators are required to input their credentials (username and password) that were used during the login process.
Upon successful verification of the credentials, the packet will be uploaded to the server and the operator will be redirected to the Acknowledgment
screen. This screen includes the following information:
Application ID
Timestamp of Registration
Demographic data captured
Documents uploaded
Biometric data captured
Print option
QR code for the Application ID
Option to initiate a new registration process.
Upon receipt of the acknowledgement, the packet is uploaded to the Registration Processor. Once the packet has been successfully processed, a unique identification number (UIN) is generated.
On the acknowledgement page, the operator will have two options available:
Print- The operator can click on this option to obtain a physical copy of the acknowledgement.
New Registration- The operator can initiate another registration by clicking on this option.
In summary, the aforementioned steps can be followed by the user (Operator/ Supervisor) to register an individual by capturing demographic data, documents, and biometric data in order to generate their UIN.
Masterdata is the necessary base data to run MOSIP services. The data resides in mosip_master
database. This data needs to be customized for a country specific deployment.
Masterdata may be uploaded in the following manner:
One-time bulk upload:
Default masterdata (for sandbox installation): Using Helm chart. The default data uploaded during sandbox installation is available in mosip-data.
Country specific data: Using Python scripts.
Updates: Updates to tables may be done using the Admin Portal.
The tables that need to be modified for country specific data are listed below. Other tables in mosip_master
DB are either system-filled or pre-filled and not to be modified.
Copy Excel files from mosip-data to a folder.
For all tables listed below modify lang_code
and add corresponding rows for your configured languages.
Modify the files for your deployment as per guide below.
Upload first time using scripts given here.
Subsequently, update data ONLY using Admin Portal.
MOSIP provides automation test repositories for the following:
Selenium webdriver-based Admin Portal Automation covers CRUD (create, read, update and delete) operation performed via UI with Chrome driver.
Registration test automation covers these flows: New, Update, Correction, and Lost flows.
This repository contains API automation tests. The automation is written using Java REST Assured and TestNG framework. The following modules are covered:
Pre-registration
Masterdata
Partner Management
ID Repository
IDA
Resident
Functional tests support multi-languages, i.e., the input can be provided in any of the languages configured in a given MOSIP installation.
This repository contains a test framework for end-to-end testing of MOSIP functionality. The following functionalities are covered:
Registration
Pre-registration + Registration
Authentication
Below is a list of tools required in Commons:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
PostgreSQL
Any DB client (like DBeaver, pgAdmin)
Postman (any HTTP Client)
Git
Any Editor (like Vscode, Notepad++ etc optional)
lombok.jar (jar file)
settings.xml (document)
Unzip Apache Maven and move settings.xml
to "conf" folder <apache maven unzip path>\conf
.
Install Eclipse, open the lombok.jar
file and then click Install/Update
.
Check the Eclipse installation folder to see if the lombok.jar
is added.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Open the project folder where pom.xml
is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project.
After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
For integration with any of our environments, do reach out to our team.
Commons
uses two property files, kernel-default
and application-default
, configure them accordingly. For instance
Update spring.mail.host
property to update SMTP host.
Update Url's in property files.(It can be either pointed to any remotely or locally deployed services).
Run the server by opening the config-server-start.bat
file.
To verify the config-server, hit the below URL http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label}
for instance http://localhost:51000/config/kernel/env/master
.
Commons
repo consists of two types of project- REST services and libraries.
Every REST service consist of bootstrap.properties
file in src/main/resources
.
Below properties needed to be modified in order to connect to the config server:
Services can be run using Run As -> Spring Boot App/Java Application
.
Libraries are not meant to be run alone they are projects used by commons as well as other modules of mosip to perform commons operations.
The API's can be tried with the help of Swagger-UI and Postman.
Swagger-UI of services can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config
for instance https://dev.mosip.net/v1/authmanager/swagger-ui/index.html?configUrl=/v1/authmanager/v3/api-docs/swagger-config
.
Context-path of services is present in bootstrap.properties
file in src/main/resources
of every service.
The API's can be tried using Postman. URLs and Body structures can be found in Swagger or curl command can be copied and imported in Postman.
Category | Table | Guide |
---|---|---|
To know more about each, click .
Refer .
module provides a bedrock to build and run services by providing several significant necessary technical operations. It contains common functionalities which are used by more than one module.
Download and .
For the code setup, clone the repository and follow the guidelines mentioned in the .
Download and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
.
Clone .
Refer to deploy local DB.
Secrets can be encrypted using .
Download . For windows download , linux users can run java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:{mosip-config-mt_folder_path}/config -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 {jarName}
.
For API documentation, refer .
Documents
doc_category
Categories of documents to be captured
doc_type
Specific documents related to a country
applicant_valid_document
Mapping of document category, type and applicant type
Location
loc_hierarchy_list
List of location hierarchy
location
List of locations stored in a hierarchical format
loc_holiday
Holidays specific to different locations. Used in registration centre creation.
Machine
machine_type
Example mobile, stationary. Refers to machine_spec
.
machine_spec
Model, make of the registration machine
ID Schema
identity_schema
Refer to ID Schema customisation. Update the JSON in schema_json
column of identity_schema.xlsx
dynamic_field
Dynamic dropdowns used during data capture
id_type
Only name
and descr
can be changed based on language
ui_spec
UI specification for registration and pre-registration UI screens. See UI spec guides
Registration client
permitted_local_config
List of changeable configurations by the operator
app_authentication_method
Only method_seq
can be changed
app_detail
Only name
and descr
can be changed based on language
app_role_priority
Only priority
can be changed
authentication_method
Only method_seq
can be changed
reason_list
List of reasons for a reason category
reason_category
Only name
and descr
can be changed based on language
Registration center
reg_center_type
Type of center
registration_center
List of registration centers
registration_center_h
Historical data for any modification done on a registration center. One time intialization of this table identical to registration_center
. Thereafter, the data will be system updated
reg_exceptional_holiday
Exception holiday for a registration center
reg_working_nonworking
Working and non-working day for a center
Biometrics
biometric_attribute
Only name
and descr
can be changed based on language
biometric_type
Only name
and descr
can be changed based on language
Templates
template
Only name
, descr
, file_txt
can be changed based on language
template_file_format
Only descr
can be changed based on language
template_type
Only descr
can be changed based on language
Others
blocklisted_words
List of blocked words
daysofweek_list
Only name
can be changed based on language
module_detail
Only name
and descr
can be changed based on language
process_list
Only name
and descr
can be changed based on language
status_list
Only descr
can be changed based on language
status_type
Only name
and descr
can be changed based on language
title
List of titles used in the country
zone
List of administrative zones in a country
The DataShare service is used to share data with other entrusted services and partners. The mechanism shares are the following:
Retrieves and stores data to be shared in Object Store and returns a Datashare URL.
It fetches data from the Object Store when the Datashare URL is called.
The sharing of data is controlled by the Datashare policy.
Data is encrypted before sharing it with partners. Learn more about datashare encryption.
The relationship of Datashare Service with other services is explained here. NOTE: The numbers do not signify the sequence of operations or control flow. Arrows indicate the data flow.
ABIS Handler Stage creates datashare for ABIS.
Manual Adjudication Stage creates datashare for adjudication.
Verification Stage creates datashare for verification.
Datashare Service calls Policy Manager Service to get the policy for creating shares.
It calls the Keymanager Service to encrypt data as per policy.
Stores datashare inside object store.
Retrieves datashare from the object store when the datashare URL is called.
External systems like ABIS, Print System, Adjudication system etc. calls Datashare Service to get the datashare.
Print Service creates UIN PDF and uploads to datashare through Credential.
Partner Manager Service creates credentials for CA certificates to be used by ID Authentication.
Printing Stage creates credentials for printing systems and sends the data through datashare.
ID Repository Service sends data to ID Authentication system through Credential.
OpenID-Bridge module provides AutnN and AuthZ related funtionalities.
Below is a list of tools required in OpenID Bridge:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
PostgreSQL
Any DB client (like DBeaver, pgAdmin)
Postman (any HTTP Client)
Git
Any Editor (like Vscode, Notepad++ etc optional)
lombok.jar (jar file)
settings.xml (document)
Download lombok.jar and settings.xml.
Unzip Apache Maven and move settings.xml
to "conf" folder <apache maven unzip path>\conf
.
Install Eclipse, open the lombok.jar
file and then click Install/Update
.
Check the Eclipse installation folder to see if the lombok.jar
is added.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml
is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project .
After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
1. Clone mosip-config repository.
2. OpenID Bridge uses two property files, kernel-default
and application-default
, configure them accordingly. For instance,
OpenID bridge connects to an IAM which supports Openid and Oauth. For integration with our keycloak, Please reach out to our team.
Update mosip.iam.open-id-url
property to update iam url.
Secrets can be encrypted using config server
Update Url's in property files.(It can be either pointed to any remotely or locally deployed services)
3. Download kernel-config-server.jar. For Windows, download config-server-start.bat, Linux users can run
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:{mosip-config-mt_folder_path}/config -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 {jarName}
.
5. To verify the config-server, hit the below URL: http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label}
for instance http://localhost:51000/config/kernel/env/master
Audit REST service consists of bootstrap.properties
file in src/main/resources
.
Below properties needed to be modified in order to connect to the config server:
Services can be run using Run As -> Spring Boot App/Java Application
.
For API documentation, refer here.
The API's can be tried with the help of Swagger-UI and Postman.
Swagger-UI service can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config
for instance https://dev2.mosip.net/v1/auditmanager/swagger-ui/index.html?configUrl=/v1/auditmanager/v3/api-docs/swagger-config
.
The API's can be tried using postman. URLs and Body structures can be found in Swagger or curl command can be copied and imported in Postman.
ID Authentication is built as an independent service that can be seeded with data for authentication by any system, including MOSIP. In the current design, we can have multiple IDA modules running from a single issuer.
The ID Authentication (IDA) module of MOSIP consists of the following services:
Authentication Services
OTP Service
Internal Services
The services mentioned below are used by Authentication or e-KYC Partners.
Authentication Service: used to authenticate an individual's UIN/VID using one or more authentication types.
KYC Authentication Service: used to request e-KYC for an individual's UIN/VID using one or more authentication types.
OTP Request Service is used by Authentication/e-KYC Partners to generate OTP for an individual's UIN/VID. The generated OTP is stored in IDA DB for validation during OTP Authentication.
Internal Authentication Service - The authentication service used by internal MOSIP modules such as Resident Service, Registration Processor and Registration Client to authenticate individuals.
Internal OTP Service - used by Resident Service to generate OTP for an Individual for performing OTP Authentication.
Authentication Transaction History Service - used by Resident Service to retrieve a paginated list of authentication and OTP Request transactions for an individual.
ID Authentication uses the credential data of the individuals for performing authentication.
This credential is requested by ID Repository upon any UIN insertion/update or VID creation.
WebSub invokes the credential-issuance callback in ID Authentication where the credential data is downloaded from Datashare and then stored in IDA DB.
ID Authentication needs the below keys to be generated during the deployment for usage in Authentication Service.
IDA IDENTITY_CACHE
(K18) symmetric key to encrypt and decrypt the Zero-knowledge 10K random keys
IDA ROOT
master key(K15)), IDA module
master key(K16), IDA-SIGN
master key
Base keys CRED_SERVICE
(K22), IDA-FIR
(K21), INTERNAL
(K19), PARTNER
(K20)
This is a reference application to demonstrate how authentication and KYC can be performed by Authentication Partners.
Refer to the repository for more details.
Below is the sample authentication demo UI image.
Refer to ID Authentication Configuration Guide.
To know more about the developer setups, read:
Refer API Documentation.
Audit Manager module provides audit-related functionalities.
Below is a list of tools required for auditing:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
PostgreSQL
Any DB client (like DBeaver, pgAdmin)
Postman (any HTTP Client)
Git
Any Editor (like Vscode, Notepad++ etc optional)
lombok.jar (jar file)
settings.xml (document)
1. Download lombok.jar and settings.xml.
2. Unzip Apache Maven and move settings.xml
to the "conf" folder <apache maven unzip path>\conf
.
4. Check the Eclipse installation folder to see if the lombok.jar
is added.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml
is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project.
After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successfully importing of project, update the project by right-clicking on Project → Maven → Update Project
.
1. Download Auth adapter and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
.
2. Clone mosip-config repository.
3. Refer Audit-DB-deploy to deploy local DB.
4. The audit uses two property files, kernel-default
and application-default
. Please configure them as needed. For instance,
Update the mosip.kernel.auditmanager-service-logs-location
property to update the location of log files.
Secrets can be encrypted using config server.
Update URL's in property files.(It can be either pointed to any remotely or locally deployed services)
5. Download kernel-config-server.jar. For Windows, download config-server-start.bat, linux users can run
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:{mosip-config-mt_folder_path}/config -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 {jarName}
.
6. Run the server by opening the config-server-start.bat
file.
7. To verify the config-server, hit the below URL:
http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label}
for instance http://localhost:51000/config/kernel/env/master
.
Audit REST service consist of bootstrap.properties
file in src/main/resources
.
Below properties needed to be modified in order to connect to the config server:
Services can be run using Run As -> Spring Boot App/Java Application
.
For API documentation, refer here.
The API's can be tried with the help of Swagger-UI and Postman.
Swagger-UI of service can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config
for instance https://dev2.mosip.net/v1/auditmanager/swagger-ui/index.html?configUrl=/v1/auditmanager/v3/api-docs/swagger-config
.
The API's can be tried using postman by copying CURL command below, updating host and importing in Postman.
Demographic data normalization is the process of applying rules for formatting of the demographic data (such as the address) into a common format before demographic data matching is verified during the demographic authentication in IDA. For example, for address lines, the '1st Street' can be replaced with '1 st' and 'C/o' can be removed from both the input and database data before the match is verified. These rules will be different for different languages, and may be configured/implemented differently.
For any other custom implementation of the normalization, the Demo-SDK needs to be implemented accordingly.
The below configuration is used to define the separator for normalizing regex (pattern) and the replacement word. The default is set to '='.
ida.norm.sep==
The format for configuring the name/address normalization rules for any language is given below:
ida.demo.<name/address/common>.normalization.regex.<languageCode/any>[<sequential index starting from 0>]=<reqular expression>${ida.norm.sep}<replacement string>
If replacement string is not specified, the regular expression will be replaced with empty string.
Note: It is recommended that the sequence is not broken in the middle otherwise all normalization properties will not be read for the particular type.
For non-english languages, the non-english words needs to be converted into UTF-16 and then copied to the configuration. For example, convert the Unicode characters to UTF-16.
Before conversion: ida.demo.address.normalization.regex.hin[0]=पहली${ida.norm.sep}पहला
After conversion: ida.demo.address.normalization.regex.hin[0]=\u092a\u0939\u0932\u0940${ida.norm.sep}\u092a\u0939\u0932\u093e
OTP Request Service is used by Authentication/e-KYC Partners to generate OTP for an individual's UIN/VID. The generated OTP is stored in IDA DB for validation during OTP Authentication.
The documentation here will guide you through the prerequisites required for the developer' setup.
Below are a list of tools required in ID Repository Services:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up ID Repository Services on your local system:
2. Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to "conf" folder C:\Program Files\apache-maven-3.8.4\conf
.
3. Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
.
4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
3. Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
Properties to be updated:
application-default.properties
mosip.mosip.resident.client.secret = <current_password>
.
db.dbuser.password=<password>
.
mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
Comment this out auth.server.admin.issuer.internal.uri
in application-default.properties
file because you already have this auth.server.admin.issuer.uri
, and hence there is no need of auth.server.admin.issuer.internal.uri
.
mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>
. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json
)
id-authentication-default.properties
......
......
6. Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
7. Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Auth-Otp-Service-Dev").
2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master
in VM arguments.
3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net
or qa3.mosip.net
).
4. Click Apply and then debug it (starts running).
Internal Authentication Service: The authentication service used by internal MOSIP modules such as Resident Service, Registration Processor, and Registration Client to authenticate individuals.
Internal OTP Service: used by Resident Service to generate an OTP for an Individual for performing OTP Authentication.
Authentication Transaction History Service: used by Resident Service to retrieve a paginated list of authentication and OTP Request transactions for an individual.
The documentation here will guide you through the prerequisites required for the developer's setup.
Below is a list of tools required in ID Repository Services:
JDK 11
Any IDE (like Eclipse or IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up ID Repository Services on your local system:
2. Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to "conf" folder C:\Program Files\apache-maven-3.8.4\conf
.
3. Install Eclipse, open the lombok.jar
file, wait for some time until it completes the scan for the Eclipse IDE, and then click Install/Update
.
4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately, as it is auto-configured by Eclipse.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Open the project folder where pom.xml
is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true
to build the project and wait for the build to complete successfully.
After building a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successfully importing of project, update the project by right-clicking on Project → Maven → Update Project
.
3. Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
Properties to be updated:
application-default.properties
mosip.mosip.resident.client.secret = <current_password>
.
db.dbuser.password=<password>
.
mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
Comment this out auth.server.admin.issuer.internal.uri
in application-default.properties
file because you already have this auth.server.admin.issuer.uri
, and hence there is no need for auth.server.admin.issuer.internal.uri
.
mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>
. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json
)
id-authentication-default.properties
......
......
6. Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
7. Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with the environment - "Auth-Internal-Service-Dev").
2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master
in VM arguments.
3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net
or qa3.mosip.net
).
4. Click Apply and then debug it (starts running).
The services mentioned below are used by Authentication/e-KYC Partners.
Authentication service- used to authenticate an individual's UIN/VID using one ore more authentication types.
KYC Authentication service- used to request e-KYC for an individul's UIN/VID using one ore more authentication types.
The documentation here will guide you through the prerequisites required for the developer' setup.
Below are a list of tools required in ID Repository Services:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up ID Repository Services on your local system:
2. Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to "conf" folder C:\Program Files\apache-maven-3.8.4\conf
.
3. Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
.
4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
3. Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
Properties to be updated:
application-default.properties
mosip.mosip.resident.client.secret = <current_password>
.
db.dbuser.password=<password>
.
mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
Comment this out auth.server.admin.issuer.internal.uri
in application-default.properties
file because you already have this auth.server.admin.issuer.uri
, and hence there is no need of auth.server.admin.issuer.internal.uri
.
mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>
. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json
)
id-authentication-default.properties
......
......
6. Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
7. Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Auth-Service-Dev").
2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master
in VM arguments.
3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net
or qa3.mosip.net
).
4. Click Apply and then debug it (starts running).
4. Run the server by opening the config-server-start.bat
file.
3. Install Eclipse, open the lombok.jar
file, and click Install/Update
.
The ID-Authentication Demographic data normalization mentioned here is specific to the of the . It takes the below configuration to apply the name and address normalization rules.
1. Download lombok.jar
and settings.xml
from .
For the code setup, clone the repository and follow the guidelines mentioned in the .
1. For the environment setup, you need an external JAR that is available with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
2. Clone .
4. As ID Authentication is using two properties files, id-authentication-default
and application-default
, you will have to configure them according to your environment. The same files are available for reference.
5. To run the server, two files are required- and .
For API documentation, refer .
1. Download lombok.jar
and settings.xml
from .
For the code setup, clone the repository and follow the guidelines mentioned in the .
1. For the environment setup, you need an external JAR that is available with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to the project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
2. Clone .
4. As ID Authentication is using two property files, id-authentication-default
and application-default
, you will have to configure them according to your environment. The same files are available for reference.
5. To run the server, two files are required- and .
For API documentation, refer .
1. Download lombok.jar
and settings.xml
from .
For the code setup, clone the repository and follow the guidelines mentioned in the .
1. For the environment setup, you need an external JAR that is available with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
2. Clone .
4. As ID Authentication is using two properties files, id-authentication-default
and application-default
, you will have to configure them according to your environment. The same files are available for reference.
5. To run the server, two files are required- and .
For API documentation, refer .
UIN / VID are system-generated unique identifiers provided to Residents. Residents are allowed to authenticate themselves using either UIN / VID.
What if residents are given the flexibility to create their handle (username) and use their unique handle to authenticate?
Handles can include resident's phone number, e-mail ID, or any linked functional ID / sectoral ID.
The handle can also be a custom username created through the resident portal.
Countries that have an established user base can now register users onto a relying portal using their distinctive identifiers referred to as handles. These handles are tailored to meet the specific requirements of each country, enabling users to easily access digital services and receive prompt benefits from both the government and private sector. This approach eliminates the need for users to remember a new or system generated IDs.
The implementation of custom handles involves below steps:
Mark the fields that can be used as user handles. A new attribute is introduced in identity schema, handle which accepts boolean value. More than one field in the identity schema can be marked as handle.
With phone as an example:
{"fieldCategory": "phone number", "format": "none", "type": "string", "fieldType": "default", "requiredOn" : "", **"handle" : true**},
When the user registers, collected user data should contain selectedHandles, as more than one field can be marked as handle, user can choose amongst the handle fields to use. User can also choose all of them. Client UI’s collecting user data during registration can decide to provide this option to the user or it can also set selected handles to default values as decided by the country. selectedHandles
is also a field in schema, identity
.
"selectedHandles" : {"fieldCategory": "none","format": "none","type": "array","items" : { "type" : "string" },"fieldType": "default" }
When the collected identity object is sent to the ID repository, it validates the data and accepts the handle provided it is unique amongst the registered handles.
Note: If duplicated, a request to register the user is rejected.
Once identity is successfully processed and stored in an ID-repository, identity credentials are issued to IDA to store user credentials for each ID (UIN & VID) as well for each selected handle.
ID-repository can be configured to disable issuance of user credential to IDA for both UIN or VID using below properties.
mosip.idrepo.identity.disable-uin-based-credential-request=true
If the system is configured to use more than one functional ID as a handle and if two different functional ID systems followed the same format /pattern to generate an ID, handles collision may occur.
Collision between two different functional IDs will result in denying the creation / updating of a handle for a resident.
Solution: Every handle stored is postfixed with handle type and the handle type is chosen based on the handle field ID in the identity schema. On every authenticate request, IDA will expect handle postfixed with handle_type as input.
Property mentioned below is introduced in ID repository to postfix handle type on every creation of identity.
mosip.identity.fieldid.handle-postfix.mapping={'phone':'@phone'}
Property mentioned below is introduced in Id-authentication-default.properties
file to validate the handle value based on the postfix provided in the inidivdualId
input.
mosip.ida.handle-types.regex={ '@phone' : '^\\+91[1-9][0-9]{7,9}@phone$' }
Implementing custom handles provides a user-friendly approach to user authentication without burdening end users with the need to remember additional or system generated complex IDs.
Identity Service stores, updates, retrieves identity information.
Also, retrieves and updates UIN status.
The documentation here will guide you through the prerequisites required for the developer' setup.
Below are a list of tools required in ID Repository Services (Identity Service) setup:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up ID Repository- Identity Services on your local system:
1. Download lombok.jar
and settings.xml
from here.
2. Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to "conf" folder C:\Program Files\apache-maven-3.8.4\conf
.
3. Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
.
4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
2. Clone mosip-config repository.
3. Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
4. As Id Repository is using two properties files, id-repository-default
and application-default
, you will have to configure them according to your environment. The same files are available here for reference.
Properties to be updated:
application-default.properties
mosip.mosip.resident.client.secret = <current_password>
.
db.dbuser.password=<password>
.
mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
Comment this out auth.server.admin.issuer.internal.uri
in application-default.properties
file because you already have this auth.server.admin.issuer.uri
, and hence there is no need of auth.server.admin.issuer.internal.uri
.
mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>
. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json
)
id-repository-default.properties
mosip.idrepo.db.url
mosip.idrepo.db.port
Comment out all the lines containing mosip.biometric.sdk.providers.finger
, mosip.biometric.sdk.providers.face
and mosip.biometric.sdk.providers.iris
.
Comment out this property mosip.kernel.idobjectvalidator.referenceValidator
.
mosip.idrepo.mosip-config-url=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.
6. Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
7. Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Identity-Service-dev").
2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master
in VM arguments.
3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net
or qa3.mosip.net
).
4. Click Apply and then debug it (starts running).
For API documentation, refer here.
The APIs can be tested with the help of Swagger-UI.
Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of identity-services for localhost from http://localhost:8090/idrepository/v1/identity/swagger-ui/index.html?configUrl=/idrepository/v1/identity/v3/api-docs/swagger-config#/
.
ID Repository contains the records of identity of an individual, and provides API based mechanism to store, retrieve and update identity details by other MOSIP modules. ID Repository is used by Registration Processor, ID Authentication and Resident Services.
ID Repository module consists of the following components:
Identity service
VID service
Credential service
Credential Request Generator service
Credential Feeder
Salt generator
Stores, updates, retrieves identity information.
Also, retrieves and updates UIN status.
Identity service uses Biometric SDK (server) to extract templates from provided biometric data.
Above is the entity relationship diagram illustrated for Identity service. NOTE: The numbers do not signify sequence of operations or control flow. Arrows indicate the data flow.
Key Manager encrypts/decrypts data.
Credential request generator issues credentials for new/updated UIN data.
Object Store stores/retrieves biometrics and demographic documents.
All demographic data of UIN and references to biometric and demographic files stored in object store are stored in mosip_idrepo
DB.
Partner management service retrieves online verification partners to issue credentials.
Audit logs are logged into Audit Manager.
Biometric SDK extracts the templates for input biometric data.
Auth Adapter integrates with KeyCloak for authentication.
Masterdata service retreives Identity schema based on input schema version.
WebSub publishes events related to UIN updation and auth type status updates.
Kernel ID generator generates UIN.
VID service fetches the list of VIDs associated with UIN to issue credential of update UIN and to create and activate draft VID.
VID Service provides functionality to create/update Virtual IDs mapped against an UIN. It also provides the facility to update status of VID. VIDs are created based on the VID policy defined in the configuration.
Key Manager encrypts/decrypts data.
Credential request generator issues credentials for new/updated UIN data. 3 All VID related data is stored in mosip_idmap
DB.
Partner management service retrieves online verification partners to issue credentials.
Audit logs are logged into Audit Manager.
Auth Adapter integrates with KeyCloak for authentication.
WebSub publish events related to VID updation.
Kernel ID generator generates VID.
Identity service checks the status of UIN to create VID.
Key Manager encrypts/decrypts data and also used to sign data.
WebSub subscribes to get notifications related to credential status from IDA.
DataShare creates datashare url for sharable attributes.
Identity service retrieves identity data for UIN/VID.
Partner management service retrieves policies related to credential type and also retrieves policy for bio-extraction.
Auth Adapter integrates with KeyCloak for authentication.
A credential can be defined as any document, object, or data structure that vouches for the identity of a person through some method of trust and authentication. Simply put, a credential is the thing that a person presents—in person or remotely—to say "this is who I am." The types of credentials issued in an ID system vary along multiple dimensions, depending on whether they are physical (i.e., they must be physically carried by a person in order to use them), or digital (i.e., they are machine readable and therefore can be used in a digital environment).
A credential type essentially maps to partner and data share policy.
Default credential types provided as part of sandbox deployment are given below:
auth
: Represents individual's data shared with Online Verification Partners (further used for Authentication and eKYC).
qrcode
: qrcode type is used for qrcode partners to issue qrcode related credential data.
euin
: It is used to issue credential data to partners who wish to download euin card using euin policy.
reprint
: Reprint auth type is used for issuing credential information to reprint partners.
vercred
: To issue verifiable credentials to partners, vercred credential type is used.
These types are defined in partner_policy_credential_type
table of mosip_pms
database.
New credential types may be defined as per needs of a country.
This service creates request for credential issuance.
Key Manager encrypts/decrypts data.
Auth Adapter integrates with KeyCloak for authentication.
This job will feed the existing UIN/ VID identity information to newly deployed IDA instance.
This is a one-time job that populates salts that are used to hash and encrypt data for Identity and VID services. This job must be executed before deploying these services. The following tables are populated:
uin_hash_salt
in mosip_idrepo
DB.
uin_encrypt_salt
in mosip_idmap
DB.
In MOSIP sandbox, the job is run here.
To know more about the developer setups, read:
Refer API Documentation.
This service creates request for credential issuance.
Keymanager encrypts/decrypts data.
Auth Adapter integrates with Keycloak for authentication.
The documentation here will guide you through the prerequisites required for the developer' setup.
Below are a list of tools required in ID Repository (Credential Request Generator Service) setup:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up ID Repository Services on your local system:
1. Download lombok.jar
and settings.xml
from here.
2. Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to "conf" folder C:\Program Files\apache-maven-3.8.4\conf
.
3. Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
.
4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
2. Clone mosip-config repository.
3. Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
4. As ID Repository is using two properties files, id-repository-default
and application-default
, you will have to configure them according to your environment. The same files are available here for reference.
Properties to be updated:
application-default.properties
mosip.mosip.resident.client.secret = <current_password>
.
db.dbuser.password=<password>
.
mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
Comment this out auth.server.admin.issuer.internal.uri
in application-default.properties
file because you already have this auth.server.admin.issuer.uri
, and hence there is no need of auth.server.admin.issuer.internal.uri
.
mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>
. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json
)
id-repository-default.properties
mosip.credential.service.database.hostname
mosip.credential.service.database.port
5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.
6. Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=/home/vipul/Desktop/tspl/mosip-config/sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
7. Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Credential-request-generator-dev").
2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master
in VM arguments.
3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net
or qa3.mosip.net
).
4. Click Apply and then debug it (starts running).
For API documentation, refer here.
The APIs can be tested with the help of Swagger-UI.
Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of credential-request-generator-services for localhost from https://localhost:8094/v1/credentialrequest/swagger-ui/index.html?configUrl=/v1/credentialrequest/v3/api-docs/swagger-config#/
.
VID Service provides functionality to create/update Virtual IDs mapped against an UIN. It also provides the facility to update the status of VID. VIDs are created based on the VID policy defined in the configuration.
The documentation here will guide you through the prerequisites required for the developer' setup.
Below are a list of tools required in ID Repository VID Services setup:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up ID Repository (VID Services) on your local system:
2. Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to "conf" folder C:\Program Files\apache-maven-3.8.4\conf
.
3. Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
.
4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
3. Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
Properties to be updated:
application-default.properties
mosip.mosip.resident.client.secret = <current_password>
.
db.dbuser.password=<password>
.
mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
Comment this out auth.server.admin.issuer.internal.uri
in application-default.properties
file because you already have this auth.server.admin.issuer.uri
, and hence there is no need of auth.server.admin.issuer.internal.uri
.
mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>
. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json
)
id-repository-default.properties
mosip.idrepo.db.url
mosip.idrepo.db.port
Comment out all the lines containing mosip.biometric.sdk.providers.finger
, mosip.biometric.sdk.providers.face
and mosip.biometric.sdk.providers.iris
.
mosip.idrepo.mosip-config-url=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/
(i.e. sandbox-local
folder location).
6. Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
7. Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "vid-service-dev").
2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master
in VM arguments.
3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net
or qa3.mosip.net
).
4. Click Apply and then debug it (starts running).
The APIs can be tested with the help of Swagger-UI.
Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of resident-services for localhost from http://localhost:8091/idrepository/v1/swagger-ui/index.html?configUrl=/idrepository/v1/v3/api-docs/swagger-config#/
.
The ".well-known" folder is a convention used in web development to provide a standardized location for certain files or resources that need to be publicly accessible and discoverable. It typically resides at the root level of a website or web server. The purpose of this folder is to make it easy for web clients (browsers, applications, or services) to find important files or resources related to web services and security.
MOSIP can use the ".well-known" directory to serve the following purposes:
Standardization: To provide a standardized location for specific public files and resources related to web services and security. It makes it easier for developers and web clients using MOSIP to know where to look for important information.
Security: Security-related files and resources can be placed in the ".well-known" directory, such as the public certificate for encryption and signature verification can be placed here.
Interoperability: By following the ".well-known" convention, web developers using MOSIP can ensure interoperability with various web standards and protocols. For example, MOISP shares the context file which contains the structure of its Verifiable Credentials.
Ease of Configuration: Web servers can be configured to serve files from the ".well-known" directory without needing custom configurations for each specific resource. This simplifies the server setup and maintenance process.
Transparency: For matters related to security policies and contact information, such as in the "security.txt" file, placing them in a well-known location makes it transparent and easily accessible to anyone interested in the website's security practices.
MOSIP's ".well-know" directory contains three files,
controller.json
mosip-context.json
public-key.json
The "controller.json" file is used in MOSIP to share the details of the public key using which a MOSIP-issued verifiable credential can be asserted.
The "mosip-context.json" file contains the schema of the subject in the MOSIP-issued verifiable credential.
The "public-key.json" file contains the public key using which the signature of the MOSIP-issued verifiable credential can be asserted.
1. Download lombok.jar
and settings.xml
from .
For the code setup, clone the repository and follow the guidelines mentioned in the .
1. For the environment setup, you need an external JAR that is available with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
2. Clone .
4. As Id Repository is using two properties files, id-repository-default
and application-default
, you will have to configure them according to your environment. The same files are available for reference.
5. To run the server, two files are required- and .
For API documentation, refer .
The Hardware Security Module (HSM) is a highly secure physical device specifically designed and used for cryptographic processing and strong authentication. It encrypts, decrypts, creates, stores, and manages digital keys and is used for signing and authentication. HSMs may be accessed via PKCS11 and JCE interfaces.
To simulate HSM, the default sandbox installation uses SoftHSM. SoftHSM supports PKCS11 but not JCE.
JCE is a Java keystore class implementation that connects to HSMs. HSM vendors should provide JCE support.
MOSIP highly recommends the following specifications for HSM:
Must support cryptographic offloading and acceleration.
Should provide authenticated multi-role access control.
Must have a strong separation of administration and operator roles.
Capability to support client authentication.
Must have secure key wrapping, backup, replication, and recovery.
Must support 2048, 4096-bit RSA private keys, and 256-bit AES keys on the FIPS 140-2 Level 3 Certified Memory of the Cryptographic Module.
Must support at least 10000+ 2048 RSA private keys on FIPS 140-2 Level 3 Certified Memory of the Cryptographic Module.
Must support clustering and load balancing.
Should support the cryptographic separation of application keys using logical partitions.
Must support M of N multi-factor authentication.
PKCS#11, OpenSSL, Java (JCE), Microsoft CAPI, and CNG
Minimum dual Gigabit Ethernet ports (to service two network segments) and, optionally, 10G Fibre ports could be available.
Asymmetric public key algorithms: RSA, Diffie-Hellman, DSA, KCDSA, ECDSA, ECDH, and ECIES
Symmetric algorithms: AES, ARIA, CAST, HMAC, SEED, Triple DES, DUKPT, and BIP32
Hash/message digest: SHA-1, SHA-2 (224, 256, 384, 512 bits).
Full Suite B implementation with fully licensed ECC, including Brainpool, custom curves, and safe curves
Safety and environmental compliance
Compliance with UL, CE, and FCC Part 15 Class B.
Compliance with RoHS2 and WEEE.
Management and monitoring
Support remote administration —including adding applications, updating firmware, and checking the status— from NoC.
Syslog diagnostics support
Command Line Interface (CLI) or Graphical User Interface (GUI)
Support the SNMP monitoring agent.
Physical characteristics
Standard 1U 19-inch rack mount with integrated PIN ENTRY Device or Smart Card or any equivalent security.
Performance
RSA 2048 signing performance: 10,000 per second.
RSA 2048 key generation performance: 10+ per second.
RSA 2048 encryption or decryption performance: 20000+ per second.
RSA 4096 signing performance: 2000+ per second.
RSA 4096 key generation performance: 2+ per second.
RSA 4096 encryption or decryption performance: 20000+ per second.
Should be able to backup keys, replicate keys, and store keys in offline locker facilities for DR. The total capacity is in line with the total number of keys prescribed.
Clustering minimum of 20 HSMs.
Less than 30 seconds for key replication across the cluster.
A minimum of 30 logical partitions and their license should be included in the cost.
Keystore
mosip.kernel.keymanager.hsm.keystore-type
mosip.kernel.keymanager.hsm.config-path
mosip.kernel.keymanager.hsm.keystore-pass
JCE
mosip.kernel.keymanager.hsm.jce.className
mosip.kernel.keymanager.hsm.jce.keyStoreType
mosip.kernel.keymanager.hsm.jce.keyStoreFile
mosip.kernel.keymanager.hsm.jce.<ANY_OTHER_PARAM_01>
mosip.kernel.keymanager.hsm.jce.<ANY_OTHER_PARAM_02>
The Key Manager Service provides secure storage, provisioning and management of secret data. It provides all the cryptographic operations like encryption/decryption and digital signature/verification making one trust store for all partner trust path validation. It manages the lifecycle of encryption/decryption keys, including generation, distribution, administration, and deletion.
This includes keying material such as symmetric keys, asymmetric keys, certificates and algorithm data. It is a web-based key management solution that helps consolidate, control, manage, monitor, all key generation and maintenance of key life cycle required in MOSIP.
Key Manager interfaces with key store like Hardware Security Module (HSM) and mosip_keymgr
DB.
RSA-2048 for all data encryption
AES-256 for zero-knowledge encryption
Root and Module keys reside in HSM while Base key pair reside in the DB encrypted by Module keys. All references (aliases) containing metadata of keys are present in mosip_keymgr/key_alias
table. The key_store
table contains encrypted Base keys.
The keys are identified as tuple of app_id
and ref_id
.
app_id
(or applicationId
): Typically, module name e.g. REGISTRATION
.
ref_id
(or referenceId
): Specified only for Base keys (except SIGN*). Eg. 10001_110011
* SIGN
: TBD
Root and Module keys are generated by any one of these methods:
Using Key Generator job or
Using Key Manager option in Admin portal.
After the deployment, the initial set of pre-requisite keys has to be generated by the Administrator to complete the Key Manager setup. This generation is a one-time activity, and afterwards, the Key Manager will auto-generate all the required Root key and Module master keys upon expiry of key duration.
Base keys are auto-generated (and updaded on expiry) - the administrator is not required to request for generation. The keys reside in the DB. A new key pair is generated if not found in the DB.
The default validity of the keys may be modified by updating mosip_keymgr/key_policy_def
table before generating keys.
You can revoke Root or Module key by invoking generateMasterKey
API with force attribute as true. API invalidates existing key and immediately generates new key.
You can revoke Base key by invoking revokeKey
API with the respective applicationId
and referenceId
.
Random AES 256-bit key will be generated, generated random key will be used to encrypt the actual registration packet.
Random generated key will be encrypted using the certificate received from server. Certificate contains RSA 2048 bit key.
Certificate Thumbprint will be computed.
Thumbprint will be prepend to encrypted random key for key identification.
Finally, the encrypted random key with prepended thumbprint will be concated with encrypted registration packet using #KEY_SPLITTER# as separator.
Registration packet data will be split to get the encrypted random key, encrypted registration data, certificate thumbprint.
Identifies the respective private key to decryption process.
Identified private key will be decrypted with the mapped master key.
Decrypted private key will be used to decrypt the encrypted random key.
Decrypt the registration packet using the decrypted random key.
Returns the decrypted data to REG_PROC.
Registration Client sends request to sync data service for the client configuration data.
Sync Data service requests Key Manager service to provide the reg-client specific certificate. Key identifier will be APP_ID - REGISTRATION, REF_ID - CENTER-ID_MACHINE-ID.
Key Manager service generate a new key pair, encrypts the private key with REGISTRATION master key and creates a new certificate using same master.
Returns the certificate to Sync data service. If key pair is already available and is valid, returns the available certificate.
Sync data service sends the certificate to Registration Client.
The registration packet will be encrypted using the certificate received from the server after collecting all the required data for registration, including adding the digital signatures required to the registration data, and before saving/writing the data on the Registration Client hard-disk.
REG_PROC sends request to decrypt the data to Key Manager service with same app_id and ref_id.
To know more about the developer setup, read Key Manager Developers Guide.
Refer API Documentation.
This a quick-read user guide for Inji (Resident Mobile Application). To refer to detailed Inji documentation, click here.
Prerequisite: Build Inji
code to generate an apk
file. Transfer the apk
file on to a smart phone on which it is to be installed.
On the Home screen, a few tooltips are displayed after the initial setup to guide the user with the next steps.
It is recommended to keep your digital credentials (ID) with you at all times. To get started with the app, Add IDs to your profile.
There are two ways by which one can download their VC:
Downloading VC using the UIN/ VID feature
Downloading VC using the Application ID feature
Below are the steps to download the credentials using the UIN/ VID option:
Click on the ID card generated to view the following details:
At times, when the resident/user does not have their UIN/ VID, but they possess the Registration ID or PRID, they can make use of this feature to download their digital credentials.
After entering the Application ID, click on Get UIN/VID and follow the steps mentioned in the flow above.
Prerequisites:
Two or more devices with the Resident Mobile app installed are required for sharing credentials.
All required permissions like Bluetooth, location and camera access are enabled on both the devices.
The parties involved are mostly likely to be a Resident who would want to share their credentials with a Relying party (can be with a banker/ health worker/ etc).
Let us understand sharing of credentials with an example. Assuming that a Resident is wants to share their credentials with a Relying/ requesting party on the receiver's phone. The steps that both the parties have to follow is illustrated below:
Enable required permissions on both devices to get started.
Connectivity details displayed on the Sharing and Requesting device.
Once the connection is made, the Sharing ID
screen is displayed on the Resident' phone with the name of the Requesting device. Here, the sharing party can enter the reason for sharing their credentials and tap on Accept request and choose ID
.
Incoming VC on requested device. Relying party can tap Accept request and receive ID
to receive the VC.
Success message displayed on the Sharing and Requesting device after successful VC share.
The History
tab on the devices displays the details of the activities performed.
For instance,
On the Resident' phone, the History
tab displays the history of the shared credentials.
On the Relying party' phone, the History
tab shows the history of the received credentials.
Below are the steps for performing face authentication on the resident's phone using Inji.
Let us assume that the:
QR code on requesting phone
Scanner on Sharing Device
Connectivity details on both the devices : Sharing & Requesting device
Sharing screen after establishing the connection
Incoming VC on Requested Device:
Success pop up after successful share with face authentication on both the devices.
History on both the devices.
Below are the steps for performing face authentication on the requesting phone using Inji.
Let us assume that the:
QR code is on the requesting phone
Scanner on Sharing Device
Connectivity details on both the devices: Sharing and Requesting device
On the Requesting Device, following is displayed:
Success pop up after successful share with face auth on both the devices.
History on both the devices.
After successful download of VC, residents will have an option to activate VC for online login.
Resident clicks on Activation pending for online login
in the home page.
Resident will be taken to a detailed view page where an option to Activate
the VC is available.
Further, the resident can click on Activate
button. They will get an alert message after which they can click on Yes, I confirm
button.
The resident needs to enter the OTP sent on their registered number.
After the successful OTP match, VC will be activated for online login with the icon changing to green as shown below.
Also, the same is reflected on the home page.
In MOSIP every cryptographic key is referred by an Application ID and Reference ID.
Refer Key Manager for further details.
Modular Open Source Identity Platform (MOSIP) integrates a suite of Mock Services designed to emulate key functionalities of MOSIP services within the framework. In the development, testing, and demonstration phases, Mock Services will make available a controlled environment to evaluate MOSIP features. Developers and testers can refer to this documentation to gain a comprehensive understanding of the structure and functionality of each Mock Service within the MOSIP framework.
Mock Services are not intended to be a substitute for production systems. Instead, their purpose is to facilitate evaluation during the development and testing stages.
Faster Development and Testing: Enables rapid development and testing cycles without need to access to production systems.
Reduced Costs: Avoids the need for production resources, lowering development and testing costs.
Controlled Environment: Testing with Mock Services provides consistent and predictable behavior, ideal to isolate and troubleshoot.
Data Privacy: Sensitive data remains secure, as development and testing occur with mock data.
This document details each of the Mock Services and explains its significance within the MOSIP architecture.
Below mentioned are the current set of mock services available in MOSIP.
Simulates device services for testing, authentication, and delete registration functionalities.
Allows developers to interact with a device-service environment without a physical device.
Mock MV (Manual Verification)
Reproduces the manual verification process for testing and validation purposes.
Enables the testing of manual verification workflows without human intervention.
Simulates the functionality of the Automated Biometric Identification System (ABIS).
Facilitates testing of biometric matching, searching, and integrating with ABIS without accessing production data.
Maintains resident biometric uniqueness through de-duplication.
Interfaces with MOSIP via message queues in JSON format.
Replicates MOSIP's Biometric Software Development Kit (SDK) for testing and debugging.
Allows developers to integrate biometric functionalities into applications without connecting to a physical device.
Used for 1:N match, quality, and extraction, etc.
Simulation is available as Mock BioSDK, installed in the MOSIP sandbox.
Exposes REST APIs for 1:1 match and quality check at the MOSIP backend.
Mock SMTP (Simple Mail Transfer Protocol)
Simulates an SMTP server for testing email notifications without sending actual emails.
Enables the testing of communication workflows and email content.
Mock SMTP Server
Is installed as part of the default MOSIP installation.
Mimics real SMTP server behavior for testing and development purposes.
MOSIP uses Mock Services in the following modules:
Mentioned below are the services utilized by the Registration Processor module to facilitate the functions.
Mock MV (Manual Verification): Registration Processor module interacts with Mock MV to process the packets that are marked for manual verification.
Furthermore, the development and improvement of Mock Services is an ongoing and evolving process.
Some of the important properties that must be reviewed and modified for a specific deployment are listed below.
Configurations of each MOSIP module will be available here:
Administration
Commons
Datashare
ID Repository
Key Manager
Packet Manager
Partner Management
Pre-registration
Resident Services
Resident Mobile Application
WebSub
Mandatory Languages - Languages that the user has to fill (can be auto translated) during the pre-registration & registration.
Optional Languages - Languages that are not mandatory but provided as a choice to the user.
User selected Language - The language that the user selected at the time of login. The choices shown are union of Mandatory and Optional languages. The labels and alerts will be use the user selected language
Prefered Language - During registration of a registrant (user for whom identity is requested), he can choose his prefered language. This preference use used for all further notification (email, SMS or any other notification).
Languages for the entire system are configured in application prorperties file:
Below is a list of tools required in Key Manager:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
PostgreSQL
Any DB client (like DBeaver, pgAdmin)
Postman (any HTTP Client)
Git
Any Editor (like Vscode, Notepad++ etc optional)
lombok.jar (jar file)
settings.xml (document)
2. Unzip Apache Maven and move settings.xml
to "conf" folder <apache maven unzip path>\conf
.
4. Check the Eclipse installation folder to see if the lombok.jar
is added.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Open the project folder where pom.xml
is present.
Open the command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project.
After building, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
Key Manager uses two property files, kernel-default
and application-default
, configure them accordingly. For instance,
Key Manager needs a Keystore to store keys. Supported Keystore types: PKCS11, PKCS12, Offline, JCE.
Update URL's in property files.(It can be either pointed to any remotely or locally deployed services)
Run the server by opening the config-server-start.bat
file.
To verify the config-server, hit the below URL:
http://localhost:51000/config/{spring.profiles.active}/{spring.cloud.config.name}/{spring.cloud.config.label}
for instance http://localhost:51000/config/kernel/env/master
.
Key Manager REST service consists of bootstrap.properties
file in src/main/resources
.
Below properties needed to be modified in order to connect to the config server:
Services can be run using Run As -> Spring Boot App/Java Application
.
The API's can be tried with the help of Swagger-UI and Postman.
Swagger-UI service can be accessed from (https/http)://(<domain>/<host>:<port>)/<context-path>/swagger-ui/index.html?configUrl=<contect-path>/v3/api-docs/swagger-config
for instance https://dev2.mosip.net/v1/auditmanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config
.
The API's can be tried using Postman. URLs and Body structures can be found in swagger or curl command can be copied and imported in Postman.
Sharing screen after establishing the connection .
S No. | Key | Application ID | Reference ID | Key type | Objects | Storage | Generated by | Comment |
---|---|---|---|---|---|---|---|---|
SNo. | Partners | Application ID | ReferenceID | Partner Domain | Partner Type Code |
---|---|---|---|---|---|
S No. | Key | Key type | Objects | Storage | Generated by | Comment |
---|---|---|---|---|---|---|
Mock MDS ()
Mock ABIS ()
Supports 1:N de-duplication and adheres to Specifications.
Mock SDK ()
The module uses below mentioned Mock Services during the execution of the registration process. To capture biometric data, check the quality of the captured biometric data, etc., the following services are run:
Mock MDS (): The Registration Client module interacts with Mock MDS to capture biometric data during the registration. This facilitates the development of simulated biometrics, which are crucial for finalizing the registration process and generating the Unique Identification Number (UIN).
Mock SDK (): The Registration Client module interacts with mock SDK to perform 1:N match for biometrics, extracts biometric templates, and checks the quality of the captured biometrics.
Mock Services help to process packets by providing support to emulate key functionalities such as search for the duplicate biometric data, to perform manual verification, and to check the quality of the captured biometric data.
Mock ABIS (): Registration Processor module interacts with mock ABIS for testing matching performance and error handling.
Mock SDK (): Registration Processor module interacts with Mock SDK to check the quality of the captured biometrics and for authentication purposes.
module also utilizes the mock services during development, testing, and demonstration phases. It uses Mock SDK to carry out the biometric authentication.
Properties that are shared across all modules are written in the file .
Module-specific properties are written in respective *.properties
files in
Config server is a that serves the above properties to modules during run-time. The property files are downloaded when an application starts. The config server is installed as part of .
Refer to .
Refer to .
The i18n file for the respective language has to be added to the artifactory . The language codes are as per
To get an overview of Key Manager, refer .
1. Download and .
3. Install Eclipse, open the lombok.jar
file and then click Install/Update
.
For the code setup, clone the repository and follow the guidelines mentioned in the .
Download and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
.
Clone .
Refer to deploy local DB.
Secrets can be encrypted using .
Download . For Windows, download , Linux users can run java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:{mosip-config-mt_folder_path}/config -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 {jarName}
.
For API documentation, refer .
Key type
Location
Issuer
Purpose
Example
Updation method(on expiry)
Root
Self signed
Root
Key Generator job or Admin Portal
Automatic
5 years
Module
Root
Signing, encryption of Base keys
Key Generator job or Admin Portal
Automatic
3 years
Base
Database
Module
Encryption of registration packet etc.
Automatic
Automatic
2 years
K1
Kernel Root
ROOT
-
RSA 2048
Private key, self signed certificate
HSM-1
Country
Auto generated by key generator
K2
Registration
REGISTRATION
-
RSA 2048
Private key, certifcate signed by Kernel Root
HSM-1
Country
Auto generated by key generator
K3
PreReg
PRE_REGISTRATION
-
RSA 2048
Private key, certifcate signed by Kernel Root
HSM-1
Country
Auto generated by key generator
K4
Kernel Sign
KERNEL
SIGN
RSA 2048
Private key, certifcate signed by Kernel Root
HSM-1
Country
Auto generated by key generator
K5
Registration Processor
REGISTRATION_PROCESSOR
-
RSA 2048
Private key, certifcate signed by Kernel Root
HSM-1
Country
Auto generated by key generator
K6
PMS
PMS
-
RSA 2048
Private key, certifcate signed by Kernel Root
HSM-1
Country
Auto generated by key generator
K7
ID Repo
ID_REPO
-
RSA 2048
Private key, certifcate signed by Kernel Root
HSM-1
Country
Auto generated by key generator
K7.1
ID Repo
ID_REPO
demographic_data
RSA 2048
Private key, certifcate signed by ID Repo
KeyMgr DB
System
Auto-generated when accessed
K7.2
ID Repo
ID_REPO
biometric_data
RSA 2048
Private key, certifcate signed by ID Repo
KeyMgr DB
System
Auto-generated when accessed
K7.3
ID Repo
ID_REPO
identity_data
RSA 2048
Private key, certifcate signed by ID Repo
KeyMgr DB
System
Auto-generated when accessed
K7.4
ID Repo
ID_REPO
uin
RSA 2048
Private key, certifcate signed by ID Repo
KeyMgr DB
System
Auto-generated when accessed
K7.5
ID Repo
ID_REPO
credential_request
RSA 2048
Private key, certifcate signed by ID Repo
KeyMgr DB
System
Auto-generated when accessed
K8
Resident Services
RESIDENT
-
RSA 2048
Private key, certifcate signed by Kernel Root
HSM-1
Country
Auto generated by key generator
K9
Kernel Identity Cache
KERNEL
IDENTITY_CACHE
AES 256
Symmetric key
HSM-1
Country
Auto generated by key generator
K10
Registration Client (TPM)
-
-
RSA 2048
Private key, certificate
Client TPM (private key), Server DB (Certificate)
Registration Client Software
Auto generatde by Registration Client Software in TPM
K11
Registration Client Packet Encryption
REGISTRATION
CenterID_MachineID
RSA 2048
Private key, certificate signed by registration
Server DB (private key), Client DB (Certificate)
System
Auto-generated when accessed
K12
Data Share (10000 keys) for zero knowledge encryption
-
-
AES 256
Symmetric key, encrypted by Kernel Identity Cache
KeyMgr DB
System
Auto generated by key generator
K13
CA / Sub-CA certificates
-
-
X.509
Certificates
PMS DB
CA
Manually Uploaded
K14
PARTNER
PartnerID
X.509
Certificates signed by CA
PMS DB
Partners
Manually Uploaded
K15
IDA Root
ROOT
-
RSA 2048
Private key, self signed certificate
HSM-2
Country
Auto generated by key generator
K16
IDA
IDA
-
RSA 2048
Private key, certificate signed by IDA Root
HSM-2
Country/IDA Partner
Auto generated by key generator
K17
IDA Sign
IDA
SIGN
RSA 2048
Private key, certificate signed by IDA Root
HSM-2
Country
Auto generated by key generator
K18
IDA Identity Cache
IDA
IDENTITY_CACHE
AES 256
Symmetric key
HSM-2
Country
Auto generated by key generator
K19
IDA Internal
IDA
INTERNAL
RSA 2048
Private key, certificate signed by IDA
IDA DB
System
Auto-generated when accessed
K20
IDA Partner
IDA
PARTNER
RSA 2048
Private key, certificate signed by IDA
IDA DB
System
Auto-generated when accessed
K21
IDA FIR
IDA
FIR
RSA 2048
Private key, certificate signed by IDA
IDA DB
System
Auto-generated when accessed
K22
IDA Cred Service
IDA
CRED_SERVICE
RSA 2048
Private key, certificate signed by IDA
IDA DB
System
Auto-generated when accessed
PK1
ABIS
PARTNER
mpartner-default-abis (or partner ID)
AUTH
ABIS_Partner
PK2
Device Providers
PARTNER
Partner ID
DEVICE
Device_Provider
PK3
Print Service Provider
PARTNER
mpartner-default-print (or partner ID)
AUTH
Credential_Partner
PK4
Auth Providers or Relying Party
PARTNER
Partner ID
AUTH
Auth_Partner
PK5
FTM Providers (per Chip Model)
PARTNER
Partner ID
FTM
FTM_Provider
PK6
MISP
PARTNER
Partner ID
AUTH
MISP_Partner
PK7
Manual Adjudicator
PARTNER
mpartner-default-manual-adjudication (or partner ID)
AUTH
Manual_Adjudication
PK8
IDA system
PARTNER
mpartner-default-auth (or partner ID)
AUTH
Online_Verification_Partner
PK9
Resident Services
PARTNER
mpartner-default-resident (or partner ID)
AUTH
Credential_Partner
DKL0
Device key SBI CL 1.0
RSA 2048
Private key, self signed certificate
Host machine TPM/key store
Auto generated by SBI Service
DKL1
Device key SBI CL2.0
RSA 2048
Private key, self signed certificate
SBI Service
Auto generated by SBI Service
FK1
FTM key
RSA 2048
Private key, FTM Provider issued certificate
FTM
FTM
DE1
Biometric encryption random session key
AES>=256
No storage, key is created with TRNG/DRBG inside FTM
FTM
FK2
Secure boot
RSA>=256
Private key, self signed certificate
FTM
FTM Provider
Key never leaves FTM
A registration packet is a zipped, encrypted file containing ID information of an individual. It contains meta information about operator/supervisor, registration center, machine, devices etc.
Example zipped file:
10001100771006920220128223618-10001_10077-20220128223618.zip
Naming convention: appid-refid_timestamp.zip
refid: centerid_machineid
*_id.zip
: Applicant demographic/biometric/document fields which are marked as "pvt" or "kyc" or "none" in ID Schema.
*_id.json
: Meta information (process, encrypted hash, signature, schema version etc.) for *_id.zip
file.
*_evidence.zip
: Applicant's demographic/biometric/document fields which are marked as "evidence" or "none" in ID Schema.
*_evidence.json
: Meta information (process, encrypted hash, signature, schema version etc.) for *_evidence.zip
file.
*_optional.zip
: Applicant demographic/biometric/document fields which are marked as "optional" or "none" ID Schema.
*_optional.json
: Meta information (process, encrypted hash, signature, schema version etc.) for *_optional.zip
file.
Note: this is a sample packet and doesnot mean a particular information will be always available in same packet. The fields are populated based on the fieldCategory set in schema json.
Id
Evidence
Optional
See sample packet.
Partner policies control the data that needs to be shared with a partner. The policies reside in auth_policy
table of mosip_pms
DB.
Policies are not applicable for Device Provider, FTM Provider and MISP Partner as data is not shared with them.
Refer to the default policies loaded while installing MOSIP.
Common policies are grouped example 'Telecom', 'Banking', 'Insurance' etc.
Partner Management Services (PMS) module provides the following services:
Partner Management Service
Policy Management Service
For an overview of role of partners in MOSIP, refer here.
Provides various partner services like onboarding partners and providing partner data to other modules.
The diagram below illustrates the relationship of this service to other MOSIP services.
Certificates of partner are uploaded to Key Manager as part of onboarding.
Registration processor fetches ABIS datashare policy from PMS.
PMS sends notification messages to partners via notification service (of Kernel).
Audit logs are logged into Auditmanager.
ID Repository fetches credential data share partners and their polices from PMS.
All PMS data is stored in mosip_pms
DB.
Certificates of Authentication Partners are send to IDA module as IDA runs independently. The certs are shared using Datashare (which futher uses Websub to share data with IDA).
This service manages partner policies.
Audit logs are logged into Auditmanager.
All policies are stored stored in mosip_pms
DB.
Datashare service fetches partner policies and shares data with partners accordingly.
To know more about the partner portal, refer Partner Management portal.
To know more about the developer setup, read Partner Management Services Developers Guide.
Refer API Documentation.
Packet Manager performs the following functions:
Reads/writes registration packets from/to Object Store.
Performs in-memory encryption and decryption of packets.
Performs security checks, checksum, file validations, ID object validations etc. on the registration packet.
Provides packet information to other services via APIs. In case of multiple packets associated with an ID, pulls information from packets based on configured priority. (See packetmanager.default.priority
).
Packet Manager runs as a service and is also available as a library.
The relationship of Packet Manager with other services is explained here. NOTE: The numbers do not signify sequence of operations or control flow. Arrows indicate data flow.
Resident Services uses Packet Manager library to create packet.
Registration Processor reads packet data using Packet Manager service.
Packets are stored and retrieved from Object Store.
Audit logs.
Encryption and decryption of packet.
Registration Client uses Packet Manager library to create packets.
Refer Registration Packet Structure.
Refer API Documentation.
This guide enables the Device provider partner to use the partner portal effectively. Below is the workflow:
The partner self-registers through the portal.
Partner admin uploads the CA certificate.
Partner admin or Partner uploads the partner certificate.
Partner admin or Partner creates device details.
Partner admin approves or rejects device details.
Partner admin or Partner creates SBI details.
Partner admin approves or rejects SBI details.
Partner admin or Partner maps devices and SBI.
The Device Provider partner can register themselves on the MOSIP PMS portal by clicking Register on the landing page.
They need to fill up a form with the details below:
First and Last name
Organization Name
Partner type (Device Provider)
Address, e-mail, phone number
Username and password
To view the details entered, click Home to see the dashboard.
The Partner admin needs to upload the CA certificate to enable the partner for using the portal. To do so, the Partner admin:
Clicks Upload CA Certificate option on the left navigation pane of the partner portal.
Selects the Partner Domain.
Chooses the certificate to upload (only files with extensions such as .cer or .pem).
Clicks Upload.
The uploaded certificates can be viewed by clicking on View Certificates-> View
.
Similarly, the Partner certificates can be added by the Partner admin/ partner.
The certificate can be uploaded by clicking Home-> Upload Certificate -> Upload.
The certificate can be viewed by clicking Home-> View Certificate ->View.
The partner can add devices to the portal. To do so,
Partner clicks Device details-> Create Device
.
Enters the necessary details to create/add devices like:
Partner Name
Device Type and Sub Type
Make and Model
Click Save.
The Partner Admin can choose to approve/reject the device details entered by the partner.
The Partner can create SBI by filling in the required details.
The Partner Admin can choose to approve/reject the SBI details entered by the partner.
The partner can map the device with an SBI.
Below is the workflow that includes the registration process for an Auth or Credential partner and the steps that need to be followed for using the partner portal.
The partner self-registers through the portal.
Partner selects the relevant Policy Group.
Partner admin uploads the CA certificate.
Partner admin or partner uploads the partner certificate.
Partner admin or Partner maps the Partner Policy.
Partner admin approves or rejects partner policy mapping.
Partner logins after the approval and generates the API key for the approved partner policy mapping using an unique label.
The Auth/ Credential partner can register themselves on MOSIP PMS portal by clicking Register on the landing page.
They need to fill up a form with the details below:
First and Last name
Organization Name
Partner type (Authentication Partner/ Credential Partner)
Address, e-mail, phone number
Username and password
To view the details entered, click Home to see the dashboard.
On successful registration, the partner can see their username displayed on the top right corner.
Partner selects the relevant Policy Group from Map Policy Group dropdown.
Clicks Save.
The Partner admin needs to upload the CA certificate to enable the partner for using the portal. To do so, the Partner admin:
Clicks Upload CA Certificate option on the left navigation pane of the partner portal.
Selects the Partner Domain.
Chooses the certificate to upload (only files with extensions as .cer or .pem).
Clicks Upload.
The uploaded certificates can be viewed by clicking on View Certificates-> View
.
Similarly, the Partner certificates can be added by the Partner admin/ partner.
Once the certificates are uploaded,
Partner maps the policy to the Policy group by clicking on Partner Policy Mapping -> +Map Policy.
Partner enters the Partner Name.
Selects the Auth Policy Name from the dropdown.
Enters a value for the Request Details (unique value) and clicks Save.
Once this is done, you will see a message saying Policy mapping grequest submitted successfully
.
Also, the status is displayed as "In progress" and this means that the partner cannot generate the API key until the request is approved by the Partner admin.
Once the Partner Policy Mapping request is raised by the partner, the Partner admin has the privilege to approve/ reject the mapping. To do so,
Partner admin logs into the PMS portal and clicks on Partner Policy Mapping
in the left navigation pane.
Selects the policy mapping that needs an approval.
From the action menu against the policy mapping, selects Manage Policy.
Clicks Approve.
Once the request is approved, the partner can view the status being updated to Approved
instead of InProgress
.
Partner logins after the Partner Policy Mapping is approved by the Partner admin and generates the API key with an unique label. To do so,
Partner clicks Partner Policy Mapping
on the left navigation pane.
From the actions menu, click Generate API Key.
Partner enters a unique value for the Label
field.
Click Generate.
The API key is generated and can be used by the partner.
The partner can also deactivate a particular API Key by clicking on the cross-mark (X) next to it. Please note, once deactivated, it cannot be activated again. You may need to generate a new API key as per requirement.
Policy type | Partners | Description |
---|---|---|
Auth policy
AP
Specifies authentication types and KYC fields to be shared during authentication.
Datashare policy
Online Verification Partner, Credential Partner, Manual Adjudiation, ABIS partner
Specifies data to be shared with partners
This guide enables the Foundational Trust providers to use the PMP portal effectively. Below is the workflow:
Partner self-register through the portal.
Partner admin and uploads CA certificate.
Partner admin/ Partner uploads partner certificate.
Partner admin/ Partner creates FTM.
Partner admin/ Partner uploads certificate from the menu before approval/ rejection.
Partner admin approves/ rejects the FTM.
The partner can register themselves on the MOSIP PMP portal by clicking Register on the landing page.
They need to fill up a form with the details below:
First and Last name
Organization Name
Partner type (Device Provider)
Address, e-mail, phone number
Username and password
To view the details entered, click Home to see the dashboard.
The Partner admin needs to upload the CA certificate to enable the partner to use the portal. To do so, the Partner admin:
Clicks Upload CA Certificate option on the left navigation pane of the partner portal.
Selects the Partner Domain as FTM.
Chooses the certificate to upload (only files with extensions such as .cer or .pem).
Clicks Upload.
The uploaded certificates can be viewed by clicking on View Certificates-> View
.
Similarly, the Partner certificates can be added by the Partner admin or partner.
The certificate can be uploaded by clicking Home-> Upload Certificate -> Upload.
The certificate can be viewed by clicking Home-> View Certificate ->View.
The partner can create FTM details by,
Clicking FTM Details -> Create FTM
Fill up the information like Partner Name, Make and Model.
Clicking Save.
The partner can upload FTM certificates by,
Selecting Upload Certificate option from the Actions menu against the FTM created.
Entering the Partner Domain as FTM and choosing the certificate file.
Clicking Upload.
The Partner Admin can choose to approve or reject the FTM certificate uploaded. Below illustrates the workflow:
Finally, you can see the FTM activated.
Pre-registration module enables a resident to:
enter demographic data and upload supporting documents,
book an appointment for one or many users for registration by choosing a suitable registration center and a convenient time slot,
receive appointment notifications,
reschedule and cancel appointments.
Once the resident completes the above process, their data is downloaded at the respective registration centers prior to their appointment, thus, saving enrollment time. The module supports multiple languages.
User provides consent
User provides demographic information
User uploads supporting documents (Proof of Address, Birth certificate, etc.)
Note: The AID was formerly called PRID in the pre-registration context.
User selects a registration center based on postal code, geo-location, etc.
The available slots are displayed
An option to cancel and re-book the appointment is made available
An acknowledgement is sent via email/SMS
The user can print the acknowledgement containing AID and QR code.
This QR code can be scanned at the in-person registration centers.
User provides the AID/ QR code at the registration center.
The registration form gets pre-filled with the pre-registration data.
The relationship of the pre-registration module with other services is explained here. NOTE: The numbers do not signify sequence of operations or control flow
Fetch a new OTP for the user on the login page.
Log all events.
Database used by pre-reg.
Generate a new AID for the application.
Send OTP in the email/SMS to the user.
Registration Processor uses reverse sync to mark the pre-reg application as consumed.
Request data from MasterData service to get data for dropdowns, locations, consent forms etc..
Pre-registration module consists of the following services:
Partner Management module has two services:
Policy Management service
Partner Management service
The documentation here will guide you through the prerequisites required for the developer's setup.
Below are a list of tools required in Partner Management Services setup:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up Partner Management Services on your local system:
Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to conf
folder C:\Program Files\apache-maven-3.8.4\conf
.
Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
.
Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
As mentioned in the steps above, you may have to make some changes in the two properties files as per your environment.
Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "partner-management-dev").
2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master
in VM arguments.
3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net
or qa3.mosip.net
).
4. Click Apply and then debug it (starts running). In the console, you can see a message like "Started PartnerManagementService in 34.078 seconds (JVM running for 38.361)"
.
Policy management service also can run by following the above steps.
The APIs can be tested with the help of Swagger-UI and Postman.
Swagger is an interface description language for describing restful APIs expressed using JSON. Can access Swagger-UI of partner-management-services for dev-environment from https://dev.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config
and localhost from http://localhost:9109/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config
.
Can access Swagger-UI of policy-management-services for dev-environment from https://dev.mosip.net/v1/policymanager/swagger-ui/index.html?configUrl=/v1/policymanager/v3/api-docs/swagger-config
and localhost from http://localhost:9107/v1/policymanager/swagger-ui/index.html?configUrl=/v1/policymanager/v3/api-docs/swagger-config
.
Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster. It is widely used tool for API testing.
MOSIP provides backend APIs for this module along with a reference implementation of .
A pre-registration request ID known as is generated and provided to the user.
Fetch details with the help of Syncdata service.
Pre-Registration interacts with Keycloak via . The Pre-Reg module communicates with endpoints of other MOSIP modules. However, to access these endpoints, a token is required. This token is obtained from Keycloak.
Registration clients use to get the pre-reg application details for a given registration center, booking date and AID.
For more details, refer to .
MOSIP provides a reference implementation of the pre-registration portal that may be customized as per country needs. The sample implementation is available at . For getting started with the pre-registration, refer to the
To access the build and read through the deployment instructions, refer to .
For details related to Pre-registration configurations, refer to .
To know more about the developer setup, read .
Refer .
.
are the self-services which are used by the partners themselves via a portal. Partner Management Portal is a web based UI application that provides services to various types of partners.
Download lombok.jar
and settings.xml
from .
For the code setup, clone the repository and follow the guidelines mentioned in the .
For the environment setup, you need an external JAR that is available with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
Clone .
As Partner Management Services is using two properties files, partner-management-default
and application-default
, you will have to configure them according to your environment. The same files are available for reference.
To run the server, two files are required- and .
For API documentation, refer .
Download the and then import it in your postman
.
Reference implementations of modules or components are non production grade implementations that are meant to showcase a reference design or architecture. They can be used as references or starting points for customization and actual implementations.
Pre-registration portal
Admin portal
Partner Management portal
Authentication Application
Registration Client
ID object validator (kernel-ref-idobjectvalidator)
Integration with the SMS service provider (kernel-smsserviceprovider-msg91)
Integration with a Virus Scanner (kernel-virusscanner-clamav)
HSM Keystore Implementation (hsm-keystore-impl)
IAM: Keycloak
External Stage
Demo deduplication
Hazelcast Cache Provider
Demographic authentication (normalization)
Child Authentication Filter
Booking Service
UI specs of Pre-Registration module are used to configure the form fields in the Demographic Details and Document Upload functionality. UI specs are saved as a JSON file with a list of fields. Each field has a set of attributes/ properties that can be configured which affects the look and feel along with the functionality of the field. Below is the list of all the properties available for each field in the UI specs:
This guide helps in understanding the pre-registration sample UI implementation. The pre-registration portal can be used in self-service as well as in assisted mode.
Self-service mode- In this mode, residents can pre-register themselves by accessing the pre-registration portal. They can login with their email address or phone number and fill up the demographic form, upload relevant documents to book an appointment for themselves and their family/friends. Finally, they would receive an acknowledgement along with a pre-registration ID that can be used at the registration center.
Assisted mode- When used in an assisted mode, the operator could be handling the portal and helping other residents in filling up the details and creating an application on their behalf. The languages that the operator and the resident understands, may or may not be the same. If we consider a country with linguistic diversity, the possibilities increase. In such cases, the operator might log in with a language that they are familiar with, and also select a language (data capture language) familiar to the resident for filling up the demographic form and other details.
The key steps in this process are:
Login/create a user account
Create an application
Book an appointment
Receive appointment acknowledgement
To create an application, the resident/operator can follow the steps below:
Open the browser and visit the pre-registration portal.
Select the language of your preference from the dropdown.
Enter your valid email address or phone number in the text box.
Select the Captcha field.
Click Send OTP to receive a One Time Password (OTP) on your provided email address or mobile number.
Enter the OTP and click Verify.
Note: If you have not received the One-Time Password (OTP), please click on Send to request another OTP. Enter the newly received OTP to proceed. Once your OTP has been successfully verified, you will be able to create, view, or update your pre-registration application.
Once the OTP is verified, you will see a pop up for selecting the languages for data entry.
Select the languages and click Submit.
Note:
This choice will be available only if the ID issuer has configured the usage of optional languages.
Countries will have multiple languages some of which will be mandatory while others could be optional(regional languages). MOSIP provides a configuration using which a country can mandate the capture of demographic data in required number of languages (combination of mandatory and optional).
On the Demographic details page, read the Terms and Conditions and select the check box to agree. This agreement is to provide consent for the storage and processing of your personal information.
Click Accept and proceed.
Note: User consent is mandatory for creating/updating applications. The contents on this page will be displayed in all data capture languages selected.
Enter your demographic details, which includes Name, Age/DOB, Gender, Residential Status, Address, Mobile Number, Email Id, etc.
You can also change or verify your demographic details in the other selected language.
After you have filled and verified your demographic details, click Continue.
Note: The mandatory fields/labels have a *
mark. Field and button labels, error and information messages will be displayed in the user preferred language selected in the login screen. The fields displayed on this screen are configurable based on the ID schema defined by the country.
UI specs of Pre-registration module are used to configure the form fields in the Demographic Details and Document Upload functionality pages. These specs are saved as a JSON file with a list of fields.
Select the document (e.g. Passport, Reference Identity Number, etc.) from the document drop-down list.
Click Browse to locate the scanned document on your machine.
Select the file that you want to upload.
When the file is uploaded successfully, the document will appear on the right side. Verify that you have uploaded the correct document.
Repeat the steps above to upload document(s) for each applicable document category.
When adding an applicant, if a newly added applicant’s Proof of Address (POA) document is same as that of the existing user’s POA, which has been already uploaded, click Same As option and select the name of the applicant.
Click Continue to preview your application.
To change the demographic details (Name, Age, etc.), click modify at the top-right corner adjacent to the Demographic details section.
To modify the uploaded documents, click modify at the bottom-right corner adjacent to the Documents Uploaded section and make changes.
To add a new applicant, click Add Applicant. On clicking the Add Applicant option, you will be navigated to the Demographic details page to provide Consent and proceed with providing the required demographic data and upload of documents.
Click Continue.
On Your Applications page, click Create New Application to generate a new application.
Once the application is created, there could be multiple statuses depending on the data filled by the user/resident or the actions performed by them. The user can view all the pre-registration applications created by them in the Dashboard. The different statuses with a brief explanation are mentioned below:
The applications are sorted and displayed by the order of creation of application. The last application created appears first in the list.
If the user visits the registration center and consumes the appointment, then the application will be removed from the list.
If the appointment date has passed, the status changes to "Expired" and is retained on the dashboard for further rebooking/modification as required.
The recommended registration centers are automatically displayed based on your demographic details (Postal Code)
On the Book Appointment page, you can find a registration center through the three options as follows:
Click Nearby centers to view the registration centers based on your geographical location.
Use the search box to find the registration center based on your search criteria.
Click Recommended Centers to view registration centers based on your demographic details. (Postal Code)
Click Continue.
Note: The default display of registration centers will be based on the Postal Code of the user. To modify this setting, please update the location hierarchy in the pre-registration-default.properties
file using the property: preregistration.recommended.centers.locCode
.
Select your preferred date from the list of available calendar days and the number of available bookings.
The list of available time slots for your selected date is categorized between Morning and Afternoon.
Select your preferred time slot from the list.
Select the particular applicant name to book an appointment (click + to add the applicant). Note: On clicking the Add Applicant option, you will be navigated to the Demographic Details page to provide Consent and proceed with providing the required demographic data/documents.
Verify the time slot(s) as selected against the applicant name(s).
Click Continue.
On the confirmation pop-up, click Confirm.
Click OK.
After successful completion of the Pre-registration application, you will receive an acknowledgment on the registered phone number (SMS) or email address as per details provided in the demographic form.
The acknowledgement contains the following information: name, pre-registration ID, age/DOB, mobile number, email id and registration center details, appointment date, appointment time)
A QR code containing the pre-registration ID is generated. This QR code can be scanned at the registration center to fetch the details to be used during the registration process.
You can print, download, email or SMS your acknowledgment.
To print your acknowledgement, click Print.
To download your acknowledgement, click Download PDF.
To add the additional recipient(s) to receive the acknowledgment of your application, follow these steps:
Click Send Email/SMS.
Enter the mobile number and/or enter the email ID.
Click Send to receive the acknowledgement on your provided e-mail address or mobile number.
On Your Applications page, select the check box for the applicable applicant.
Click Book/Modify Appointment to re-book an appointment (on the top right corner)..
The user can select any appointment date available and the appointment slot available
A user cannot re-book the appointment if the appointment booking is less than 48 hours (configurable) from the time of booking
On Your Applications page, click on delete icon against pre-registration application of an applicant, a pop-up window appears on the screen.
Select the Discard entire application option in the pop-up window.
Click SUBMIT to discard your application.
On Your Applications page, click on delete icon against pre-registration application of an applicant, a pop-up window appears on the screen.
Select Cancel appointment and save the details option in the pop-up window.
Click SUBMIT to cancel an appointment.
Following a successful appointment cancellation, the system unlocks the time slot of the registration center to ensure that someone else can book it.
The documentation here will guide you through the pre-requisites required for Pre-registration developer setup.
JDK 11
Any IDE (Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
lombok.jar (file)
MOSIP Pre-registration specific JARs: The version will depend on which Pre Registration branch you have cloned. If it is "release-1.2.0.1" then you can download 1.2.0.1.B1 or 1.2.0.1.B2 version of below jars whichever is available.
Notepad++ (optional)
Fork the MOSIP Pre-registration repository from Github MOSIP repository to your GitHub account.
Clone the forked repository into your local machine.
git clone https://github.com/${urgithubaccname}/pre-registration.git
git remote add upstream https://github.com/mosip/pre-registration.git
git remote set-url --push upstream no_push
git remote -v
git checkout -b my-release-1.2.0.1
git fetch upstream
git rebase upstream/release-1.2.0.1
Inside settings.xml
change local repository directory to your directory name where .m2 folder
is located. E.g.: <localRepository>C:/Users/username/.m2/repository</localRepository>
Add settings.xml
inside .m2 folder
(Maven Folder). E.g.: C:\Users\username\.m2
Import the project in Eclipse IDE and it starts updating Maven projects configuration, refreshing workspaces, project starts building (downloading sources, javadoc).
Add downloaded lombok.jar
to project, click on downloaded JAR and install specifying Eclipse IDE(eclipse.exe) location.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
Add MOSIP Pre-registration specific JARs from Maven central:
Adding JARs to Build Path: Right click on service -> Build Path -> Configure Build Path -> click on Classpath -> Add External JARs -> Add required JARs -> Apply and close.
Add auth-adapter
, transliteration
, ref-idobjectvalidator
, virusscanner
, lombok
JARs to pre-registration-application-service
, pre-registration-datasync-service
classpath.
Add auth-adapter
, lombok
JARs to pre-registration-core
, pre-registration-batchjob
, pre-registration-captcha-service
, pre-registration-booking-service
classpath.
Run mvn clean install -Dgpg.skip=true
command to build locally and to execute test cases.
Update Maven dependencies: Maven syncs the Eclipse project settings with that of the pom. It downloads dependencies required for the project.
Build and run the Project.
To run the pre-registration-application-service locally without config server, update values in application.properties and bootstrap.properties:
spring.cloud.config.uri=https://localhost:8080
spring.cloud.config.label=develop
spring.cloud.config.name=pre-registration
spring.application.name=pre-registration-application-service
spring.profiles.active=default
Point below urls to a valid env which has MOSIP setup:
mosip.base.url=https://yourenvurl
auth-token-generator.rest.issuerUrl:https://iam.yourenvurl/auth/realms/mosip
javax.persistence.jdbc.password: XXXXXX
javax.persistence.jdbc.url=jdbc:postgresql://yourenvurl:5432/mosip_prereg
mosip.batch.token.authmanager.password: XXXXXX
mosip.iam.adapter.appid=prereg
mosip.iam.adapter.clientsecret=XXXXXX
auth.server.admin.issuer.uri=https://iam.yourenvurl/auth/realms/
Fork the Pre-registration UI repo to your GitHub account.
Clone the forked repository into your local machine.
git clone https://github.com/${urgithubaccname}/pre-registration-ui.git
git remote add upstream https://github.com/mosip/pre-registration-ui.git
git remote set-url --push upstream no_push
git remote -v
git checkout -b my-release-1.2.0.1
git fetch upstream
git rebase upstream/release-1.2.0.1
Install all dependencies with npm install
.
Install Angular JS npm install -g @angular/cli
.
Start the Angular JS server ng serve
.
Open http://localhost:4200
to access the application.
You will face CORS issue since API Services are hosted on https://{env}
.
Update the API services BASE_URL
in config.json
:
config.json
is found inside assets directory.
E.g.: C:\MOSIP\pre-registration-ui\pre-registration-ui\src\assets\config.json
Create a new file named proxy.conf.json
:
Location should be in C:\MOSIP\pre-registration-ui\pre-registration-ui\proxy.conf.json
project folder.
Start the server by executing ng serve --proxy-config proxy.conf.json --ssl true
.
Open the browser, load the app with https://localhost:4200
.
For API documentation, refer here.
The APIs can be tested with the help of Swagger-UI and Postman.
Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of pre-registration here:
Pre-registration Application service : https://{env}/preregistration/v1/application-service/swagger-ui.html
Pre-registration Datasync Service : https://{env}/preregistration/v1/sync/datasync-service/swagger-ui.html
Pre-registration Captcha service : https://{env}/preregistration/v1/captcha/swagger-ui.html
Pre-registration Booking service : https://{env}/preregistration/v1/appointment/booking-service/swagger-ui.html
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. Data is captured in the form of registration packets and is cryptographically secured to ensure that there is no tampering. The captured information is packaged and sent to the server for further processing.
Registration Client is featured to allow an operator to choose the operation language. Option to select their preferred language is provided on the login screen.
Data collection during registration client supports more than one language at a time.
Before starting any registration process, the operator can choose the languages amongst the configured ones.
The Registration Client can be operated by an operator who can be either a Supervisor or an Officer. They can login to the client application and perform various activities. The Supervisor and the Officer can perform tasks like Onboarding, Synchronize Data, Upgrade software, Export packet, Upload packets, View Re-registration packets, Correction process, Exception authentication, etc. In addition to this, the Supervisor has exclusive authority to Approve/reject registrations.
The relationship of Registration Client with other services is explained here. NOTE: The numbers do not signify sequence of operations or control flow.
Registration Client connects to the Upgrade Server to check on upgrades and patch downloads.
All the masterdata and configurations are downloaded from SyncData-service.
Registration Client always connects to external biometric devices through SBI.
Registration Client scans the document proofs from any document scanner.
Acknowledgement receipt print request is raised to any connected printers.
Packets ready to be uploaded meta-info are synced to Sync Status service. Also, the status of already uploaded packets are synced back to Registration Client.
All the synced packets are uploaded to Packet Receiver service one by one.
The image below shows the setup of Registration Client Host machine.
Registration Client comprises of JavaFX UI, Registration-services libaries and any third party biometric-SDK.
SBI is allowed to run on loopback IP and should listen on any port within 4501-4600 range. More than one SBI can run on the host machine. Registration Client scans the allowed port range to identify the available SBI.
Registration Client connects to local Derby database. This is used to store all the data synced.
All the completed registration packets are stored under packetstore directory.
.mosipkeys
directory is used to store sensitive files. db.conf
under this directory stores encrypted DB password. This is created on the start of registration client for the first time.
TPM - is the hardware security module used to get machine identifier, to secure DB password, prove the client authenticity on auth requests and packets created in the host machine.
The registration packets and synced data are stored in the client machine.
Most of the synced data are stored in the Derby DB. Derby DB is encrypted with the bootpassword.
Derby DB boot password is encrypted with machine TPM key and stored under .mosipkeys/db.conf
.
Synced UI-SPEC/script files are saved in plain text under registration client working directory. During sync, SPEC/script file hash is stored in derby and then the files are saved in the current working directory. Everytime the file is accessed by the client performs the hash check.
Synced pre-registration packets are encrypted with TPM key and stored under configured directory.
Directory to store the registration packets and related registration acknowledgments is configurable.
Registration packet is an signed and encrypted ZIP.
Registration acknowledgment is also signed and encrypted with TPM key.
Blueprint of registration forms to be displayed in registration client are created as json called as UI-SPEC.
Every process ( NEW / LOST / UPDATE UIN / CORRECTION ) has its own UI-SPEC json.
Kernel-masterdata-service exposes API's to create and publish UI-SPEC.
Published UI-SPEC json are versioned.
Only published UI-SPEC are synced into registration-client.
UI-SPEC json files are tamper proof, client checks the stored file hash everytime it tries to load registration UI.
UI-SPEC json will fail to load if tampered.
This guide contains all the details you may want to know about the operator onboarding.
To generate the first operator in MOSIP eco-system, refer to the steps below.
The Admin needs to:
Create the role Default in KeyCloak with all the other roles.
Create the operator' user account in KeyCloak.
Assign the operator user account with the Default role.
Perform Zone and Center mapping for the operator using the Admin Portal.
The operator will need to:
Download the latest registration client and login with the credentials set in KeyCloak. The operator will automatically skip Operator/Supervisor onboarding and reaches the home page of the registration client.
Register themselves in MOSIP and get a RID and UIN.
Once the operator is registered:
The Admin changes the role of the operator to either REGISTRATION_OFFICER or REGISTRATION_SUPERVISOR.
Deletes the role Default from KeyCloak so that no other user has the role Default.
This operator can now register and onboard other Supervisors and Officers.
Admin needs to map the operator' UIN in KeyCloak under Attributes with attribute name as individualId
.
Admin needs to remove the "Default" role mapping for the operator' user account if it exists.
The operator needs to login (password based) to the Registration Client using Keycloak credentials.
The operator needs to ensure that the Registration Client machine is online.
The operator will land into the below page and needs to click on Get Onboarded
The operator needs to provide their biometrics and click Save.
All the biometric modalities displayed in the Operator biometrics page must be captured before clicking on Save.
Captured biometrics quality must be greater than or equal to the threshold displayed in the UI.
Note- The threshold values are configurable and can be set as per the ID issuer.
Note:
After successful onboarding of the operator, the templates are extracted from the captured biometrics using configured Bio-SDK. The extracted templates are stored in Derby DB. This can be used later for operator' biometric-authentication and also for local de-duplication checks during registration.
After the first login and successful on-boarding, the registration client would mandate the operator to login with the configured authentication mode decided by the administrator.
Any number of operators can login to a registration client machine but they need to be mapped to the same center where the machine is onboarded.
Login operator' user ID is case-insensitive.
Summarizing, on-boarding of an operator is successful only if,
The operator is active and not block listed.
The operator and the machine belongs to the same center.
The operator's User ID is mapped to their UIN.
The operator's biometric authentication is successful during on-boarding.
The system is online during on-boarding.
Operator logs into Registration Client for the first time and is redirected to Onboarding screen. Here, they need to capture all their biometrics and then click SAVE button.
Success/Failure response sent back to Registration Processor based on the authentication result.
Registration Processor sends back this response to Registration Client.
After successful authentication, the captured biometrics are sent to configured Bio-SDK to extract templates.
The extracted templates are stored in local Derby DB.
These templates stored in local DB can be used later for operator's biometric-authentication and also for local de-duplication checks during registration.
MOSIP supports single factor and multi factor login including password, iris, fingerprint, and face authentication for registration client. An administrative configuration setting determines the mode of authentication login.
The registration client can authenticate an operator in offline mode using the locally stored biometrics templates (face/finger/iris) and password hash.
The registration client temporarily locks the operator’s account in case they provides an invalid password/fingerprint/iris/face for X times continuously to login (X is configurable). The temporary account lock lasts for X minutes (X is again configurable).
An Operator can logout of the registration client by:
Clicking on the Logout button,
Closing the registration client,
Being in-active on the registration client for configured amount of time after which they are 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 and stored (except for PII data).
Note- Registration client provides an alerts to the operator ‘X’ minutes before reaching the auto logout time limit. Registration client displays a countdown timer in the alert. The operator can choose to dismiss the alert and continue working. This will also reset the timer to zero.
Property Name | Details | Sample Value |
---|---|---|
Status | Description | User Action |
---|---|---|
MOSIP provides a reference implementation of a Java-based Registration Client. The code, build files for the Registration Client are available in the .
To know more about setting up the reference registration client, refer to .
To know more about the features present in the Registration Client, refer to .
To know more about the onboarding process of an operator, refer to .
Registration Client can be customized as per a country' requirements. For details related to Registration Client configurations, refer to .
Default UI Specifications loaded with Sandbox installation is available
To know more about the developer setup, read .
Onboard the operator machine using the Admin Portal. Machine' details can be extracted using the
After successful onboarding, the operator is automatically re-directed to the .
Request from Registration Client goes to for operator authentication.
Registration Processor passes this request to where it checks whether the user is mapped to a valid UIN and then matches the biometrics sent in the request with the biometrics of the mapped UIN.
Extracted templates are sent back from .
id
The id property is the unique id provided to a field to uniquely identify it. The id can be alpha-numeric without any spaces between them.
"id":"zone"
description
This is a non-mandatory property used to describe the field.
"description": "zone"
labelName
This property defines label name for the field. This property has sub-attributes as the language code (eng, fra, ara) to store data in different languages based on the country's configuration.
"labelName": { "eng": "Zone", "ara": "منطقة", "fra": "Zone"}
controlType
This property defines the kind of UI component to be used to capture data in UI. Currently the values that can be used are: • textbox (creates multiple textboxes for each field to capture input in all the languages configured for the setup) • dropdown • fileupload • date (creates a date picker) • ageDate (creates a date picker along with number toggle to provide age directly) • checkbox (creates a toggle checkbox for the field which can be checked or unchecked) • button (creates dropdown options as buttons, which user can select easily)
inputRequired
This property decides if the field is to be displayed in the UI form or not. It is useful for some internal fields which do not need any input from the user.
required
This is a mandatory property which decides if the field is a required form field or not. If true, user must provide some value for the field.
type
This property defines the data type of the value corresponding to this field. The data types supported are “number”, “string” and “simpleType”. The type “simpleType” means that language specific value will be saved along with the language code.
fieldType
This property is relevant when control type is “dropdown” or “button”. It defines if the field is of type “default” or “dynamic”. If it is “dynamic” then all the options for the dropdown are populated from the “master.dynamic_field” table otherwise they are populated from corresponding table example “master.gender”
subType
This is relevant for 2 cases: 1. When control type is “dropdown”/ “button” and the type is “dynamic” then “subtype” can be used to populate the options for the field with the data available in “master.dynamic_field” table. 2. When the control type is “fileupload”, then the property ”subtype” is used to map the field to a “code” in the “master.doc_category” table.
validators
* This property enables us to add the list of language specific validators for the field. * Each validator can have the below fields, “langCode”, “type”, “validator”, “arguments”, “errorMessageCode” * The “type” defines the validation engine type. * The “validator” gives the pattern/ methodName/ scriptName/ expression * The “arguments” array to is used to hold parameter or dependent field ids required for validation * The “errorMessageCode” can be given to add custom error message which will be shown to the user when the validation fails. The error message corresponding to this code will be picked from language specific i18n translation files. In case “errorMessageCode” is not given then generic error message will be displayed to the user when validation fails. Currently, regex is supported by MOSIP. If “langCode” is not added then same “validator” is used for all languages of the field.
"validators": [{ "langCode": "eng", "type": "regex", "validator": "^(?=.{0,50}$).*", "arguments": [], "errorMessageCode": "UI_1000" },{ "langCode": "ara", "type": "regex", "validator": "^[A-Z]+$", "arguments": [] },{ "langCode": "fra", "type": "regex", "validator": "^[A-Z]+$", "arguments": [] }]
transliteration
If enabled, then value entered by user in one language is transliterated into other.
locationHierarchyLevel
This attribute is mandatory for the location dropdown fields. The value will be as per corresponding location hierarchy level from the master.loc_hierarchy_list table.
{ "id":"region", "controlType":"dropdown", "fieldType":"default", "type":"simpleType", "parentLocCode":"MOR", "locationHierarchyLevel":1 ..}
parentLocCode
This attribute is to be used only for location dropdown fields and it is optional. The corresponding location dropdown will be pre populated in UI based on the value in “parentLocCode”. If this attribute is NOT mentioned in UI specs, then the dropdown will be populated based on selection in its parent dropdown, as before. For the first dropdown, in case this attribute is not mentioned in UI specs then the value from “mosip.country.code” configuration will be used for backward compatibility.
{ "id":"region", "controlType":"dropdown", "fieldType":"default", "type":"simpleType", "parentLocCode":"MOR", "locationHierarchyLevel":1 ..}
visibleCondition
The property is used to define an expression using json-rules-engine which will decide the visibility condition for the form field. Refer https://www.npmjs.com/package/json-rules-engine to get the syntax for the conditions.
"visibleCondition": { "all": [{ "fact": "identity", "operator":"lessThanInclusive", "value": 10, "path": "$.age" }]} This condition will make the field visible only when the “age” field value <= 10.
requiredCondition
The property is used to define an expression using json-rules-engine which will decide the required condition for the form field. Refer https://www.npmjs.com/package/json-rules-engine to get the syntax for the conditions.
"requiredCondition": { "all": [{ "fact": "identity", "operator": "equal", "value": "MLE", "path": "$.gender.0.value" },{ "fact": "identity", "operator": "equal", "value": "102", "path": "$.maritalStatus.0.value" }]} This condition will make the field required only when the “gender” field value = ‘MLE’ and “maritalStatus” field value is 102” .
alignmentGroup
* This property is used to group the fields on the screen. * If it is skipped, then all the fields will appear in same sequence (horizontally layout) as they appear in UI specs. * If you want the first and fifth field to be in same row in the screen, you can add this attribute with same group name. * The UI is responsive so it will accommodate as many fields in one row as they will fit comfortably.
containerStyle
This is used to optionally apply some CSS styles to the UI field container.
"containerStyle": { "width": "600px", "margin-right": "10px" }
headerStyle
This is used to optionally apply some CSS styles to the UI header of the field container.
"headerStyle": { "width": "600px", "margin-right": "10px" }
changeAction
This property can be added to define interaction between the 2 or more form fields when user changes value in one of them. Currently the “changeAction” supported are “copy&disable” and “copyto” ONLY.
1. "changeAction": "copyto:permanentZipcode, presentZipcode,addressCopy" When the checkbox “addressCopy” is checked the value of the field “permanentZipcode” will be copied to “presentZipcode”. 2. "changeAction":"copy&disable: permanentCountry=presentCountry, permanentAddressLine1=presentAddressLine1" When the checkbox “addressCopy” is checked the value of the field “permanentCountry” will be copied to “presentCountry” and the field “presentCountry” will be disabled. Same with “permanentAddressLine1” and “presentAddressLine1”.
Incomplete
Filled only demographic details
Upload documents and book an appointment
Pending appointment
Filled demographic details and uploaded documents
Book an appointment
Booked
Filled demographic details, uploaded documents, and booked appointment
Visit the registration center on the appointment date and time
Expired
Appointment date has passed
Re-book an appointment
Cancelled
Appointment has been cancelled
Re-book an appointment
The guide here lists down some of the important properties that may be customised for a given installation. Note that the listing here is not exhaustive, but a checklist to review properties that are likely to be different from default. If you would like to see all the properites, then refer to the files listed below.
IMPORTANT : From the LTS version, All the properties are synced to the registration-client only from registration-default.properties
file.
See Module Configuration for location of these files.
Registration Client reaches SBI on 127.0.0.1 within the below configured port range. As per SBI spec, allowed port range is from 4501 to 4600.
Timeouts in milliseconds set during any http calls to SBI.
Quality score threshold based on modality, Possible values 1 to 100
Retry attemps, Possible values 1 to 10
Quality score threshold based on modality for operator authentication, Possible values 1 to 100
Registration client can be integrated with more than one bio-sdks. Possible values for "modality-name" are "finger", "iris" or "face".
SDK implementation class full name
mosip.biometric.sdk.providers.<modality-name>.<vendor-name>.classname
SDK API version
mosip.biometric.sdk.providers.<modality-name>.<vendor-name>.version
SDK implementation class consturctor args - comma separated
mosip.biometric.sdk.providers.<modality-name>.<vendor-name>.args
SDK initialization args, this will be passed as initparams
mosip.biometric.sdk.provider.<modality-name>.<vendor-name>.<key1>=<value1>
Quality threshold used by SDK to match modality
mosip.biometric.sdk.providers.<modality-name>.<vendor-name>.threshold
Example configurations shown below for MOCK SDK named as mockvendor:
On every successful biometric capture during registration, Quality of the biometrics is computed by bio-sdk if below config is enabled. Possible values are Y/N.
mosip.registration.quality_check_with_sdk=Y
Jobs like RID sync, packet upload, status sync is carried out in batches, number of registration records to be executed in a batch on every trigger.
Only the modalities configured will be collected during operator onboarding.
On every Pre-Registration application fetch in registration page, clears all the captured data prior to Pre-Registration application fetch. Set the field id's which should not be cleared after Pre-Registration application fetch. It is comma separated list of field ids as per UI-SPEC.
Storage Location to store the downloaded Pre-Registration Packets in local system
Pre-registration applications fetch time span, No. of days before appointment date.
Comma separated list of offline job ids. Offline jobs are the jobs which are not part of manual sync.
Comma separated list of untagged job ids. Untagged jobs, which will be not part of manual sync but only from scheduler.
Comma separated list of job ids which needs Registration Client restart.
Registration batch jobs scheduler.
Default CRON expression for scheduling the Jobs.
All the identified scanner implementations will be used to list the identified devices. For each device dpi, width and height can be configured. If it is not configured, it defaults to 0.
Values in the this config mosip.registration.docscanner.id
map supports regex.
Enable GPS device for capturing the geo-location. If y, GPS device will be enabled. If n, GPS device will be disabled.
mosip.registration.gps_device_enable_flag=N
Model of the GPS Device
mosip.registration.gps_device_model=GPSBU343Connector
Timeout for connecting to GPS device
mosip.registration.gps_port_timeout=1000
GPS Serial Port in Linux machine
mosip.registration.gps_serial_port_linux=/dev/ttyusb0
GPS Serial Port in Windows machine
mosip.registration.gps_serial_port_windows=
The Distance Parameter for GPS Verification
mosip.registration.distance.from.machine.to.center=900000
To Reset Password in Registration Client
On clicking Reset password from the Actions menu present in the top right corner of Home page, it redirects the operator to the URL below which is configurable.
Enables / disables reviewer authentication on any biometric exception during registration
If enabled cross-checks of residents biometrics with locally stored operator biometric templates.
Minimum disk space required to create a packet - in MB
Registration packet store location
Number of days allowed to start Registration Client without upgrade when software upgrade is available.
mosip.registration.softwareUpdateCheck_configured_frequency=60
Time in Seconds for forced log-out of operator, if operator is idle for the specified duration
mosip.registration.idle_time=900
Time in Seconds to diplay the warning message pop-up to operator, if operator is idle for the specified duration
mosip.registration.refreshed_login_time=600
Maximum no. of days for approved packet pending to be synced to server beyond which Registration Client is frozen for registration
mosip.registration.last_export_registration_config_time=100
Maximum no. of packets pending EOD approval beyond which Registration Client is frozen for registration
mosip.registration.reg_pak_max_cnt_apprv_limit=100
Enable supervisor authentication feature. If y, supervisor approval will be enabled, else, will be disbaled
mosip.registration.supervisor_approval_config_flag=Y
No. of days beyond audit creation date to delete audits
mosip.registration.audit_log_deletion_configured_days=10
No. of days beyond registration date to delete synced and uploaded registration packet
mosip.registration.reg_deletion_configured_days=1
No. of days beyond appointment date to delete unconsumed pre-registration application data
mosip.registration.pre_reg_deletion_configured_days=1
Maximum duration to which registration is permitted without sync of master data
mosip.registration.sync_transaction_no_of_days_limit=5
Allowed number of invalid login attempts
mosip.registration.invalid_login_count=50
Used to configure the time (in minutes) for locking account after crossing configured invalid login count
mosip.registration.invalid_login_time=2
Configuration used to check if any sync job is missed / failed beyond expected days, this configuration is checked everytime operator clicks on any registration process. We follow below convention to create this config key.
mosip.registration.job api name as in sync_job_def table.frequency=value in days
#Maximum no. of days without running the Master Sync Job beyond which Registration Client is frozen for registration
mosip.registration.masterSyncJob.frequency=190
#Maximum no. of days without running the Pre-Registration Sync Job beyond which Registration Client is frozen for registration
mosip.registration.preRegistrationDataSyncJob.frequency=190
#Maximum no. of days without running the Packet Sync Status Job beyond which Registration Client is frozen for registration
mosip.registration.packetSyncStatusJob.frequency=190
#Maximum no. of days without running the Key Policy Sync Job beyond which Registration Client is frozen for registration
mosip.registration.keyPolicySyncJob.frequency=190
#Maximum no. of days without running the Registration Deletion Job beyond which Registration Client is frozen for registration
mosip.registration.registrationDeletionJob.frequency=190
#Maximum no. of days without running the Configuration Sync Job beyond which Registration Client is frozen for registration
mosip.registration.synchConfigDataJob.frequency=190
#Maximum no. of days without running the Audit Logs Deletion Job beyond which Registration Client is frozen for registration
mosip.registration.deleteAuditLogsJob.frequency=190
Date format to be displayed on acknowledgement slip, default value - dd/MM/yyyy hh:mm a
Date format to be displayed on Registration Client dashboard, default format - dd MMM hh:mm a
The registration UI forms are rendered using respective UI specification JSON. This is derived from the ID Schema defined by a country. Here, we would be discussing about the properties used in the UI specification of Registration Client.
In the Registration Client, currently, Registration Tasks(process) forms are configurable using the UI specifications.
Each process has multiple screens and each screen is rendered with one or more fields.
Default settings schema is configured as below:
All the connected devices are listed in this page.
Option to scan for SBI for any specific port range is available in this page.
If more than one device is idenitied, operator can choose amongst the listed devices to set the default device for the current login session.
Access control on this page is controlled via the settings-schema.
All the Registration Client related configuration key-value pairs are listed in this page.
Operator can set the local preference on the server configraton value, applicable only for permitted configuration keys.
Access control on this page is controlled via the settings-schema.
All the available background jobs are listed here along with their cron expression.
Every job's next and previous trigger time is listed along with the job name.
Privileged operator can update the cron expression of any job.
Synchornize Data
in home page will trigger all of these listed jobs with just one click.
If the operator needs to trigger specific job, the same can be handled in this page.
Access control on this page is controlled via the settings-schema.
Following are the metrics that are collected in the client application using the micrometer library:
JVM Memory Metrics
JVM Thread Metrics
JVM GC Metrics
JVM Heap Pressure Metrics
Processor Metrics
Class Loader Metrics
Disk Metrics
Packet Metrics based on client and server status
All the metrics collected are appended to metrics.log
file. Rolling policy of the metrics.log
is defined in registration-services logback.xml
.
Below are the challenges faced in exporting the collected metrics from client application to the server for further analysis:
Unreliable network conditions on field.
Metrics files are mostly large files, and cannot afford retries on failed attempts.
Required HTTP based metrics export.
To overcome the above challenges, Registration Client is built with tus-java-client
(version: 0.4.3) . Tusd server URL and the upload chunk-size are made configurable in the client application.
mosip.registration.tus.server.url
: This is the server URL config which specifies to which URL the metrics files are to be uploaded.
mosip.registration.tus.server.upload.chunksize
: This config defines the chunk size, which means, how much size of the file is to be uploaded at once. By default, this is given as 1024, which means 1KB
Note:
Tusd
is a popular implementation of the Tus protocol that can be used as a standalone server. It is a part of the MOSIP deployment.
Each metric json logged into metrics.log
file is tagged with machine name. Refer the below log lines with the machine names.
A job is scheduled to upload collected metrics to server from the client application.
Job runs with a fixed delay of 15 minutes.
Resumable file URLs are stored under .metrics
folder of registration client. Once the complete file is uploaded to server, the metrics file is deleted locally.
The documentation here will guide you through the prerequisites required for the developer' setup.
Below are a list of tools required in Registration Client:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
Git
Follow the steps below to set up Registration Client on your local system:
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
2. Registration Client UI is developed using JavaFX and the UI pages are fxml files which can be opened using a tool called Scene Builder
. The JavaFX integration with the Eclipse IDE is provided with the e(fx)clipse tool. Go to Help → Install New Software → Work with → Add
. Give Name and Location as mentioned in below image.
Once the software is installed, you will be prompted to restart your IDE.
4. We can change the application environment in the file registration-services\src\main\resources\props\mosip-application.properties
by modifying the property mosip.hostname
Below are the configurations to be done in Eclipse:
1. Open Eclipse and run the project for one time as Java application
, so that it creates a Java application which you can see in debug configurations.
2. Open the arguments and pass this --module-path C:\Users\<USER_NAME>\Downloads\openjfx-11.0.2_windows-x64_bin-sdk\javafx-sdk-11.0.2\lib --add-modules=javafx.controls,javafx.fxml,javafx.base,javafx.web,javafx.swing,javafx.graphics --add-exports javafx.graphics/com.sun.javafx.application=ALL-UNNAMED
in VM arguments.
3. Click Apply and then debug it (starts running). You can see a popup which shows informative messages of what is happening in background while Registration Client UI is loading and the application will be launched.
The concept here is to run nginx in the docker container from which registration-client.zip is hosted and also registration-client on the field will connect to this nginx to check for new updates or changes.
Note: We refer this nginx server as registration-client download and upgrade server.
While running the registration-client docker container we need to pass below environment variables:
Required
client_version_env
: pom version of the registration client build
client_upgrade_server_env
: public URL of this nginx server
reg_client_sdk_url_env
: URL to download sdk zip. Make sure to have SDK jar and its dependent jars in the zip.
artifactory_url_env : artifactory URL to download below mentioned runtime dependencies
“${artifactory_url}/artifactory/libs-release-local/icu4j/icu4j.jar”
“${artifactory_url}/artifactory/libs-release-local/icu4j/kernel-transliteration-icu4j.jar”
“${artifactory_url}/artifactory/libs-release-local/clamav/clamav.jar”
“${artifactory_url}/artifactory/libs-release-local/clamav/kernel-virusscanner-clamav.jar”
keystore_secret_env
: password of the keystore.p12 file
host_name_env
: syncdata-service public domain name
signer_timestamp_url_env
: URL of timestamp server to timestamp registration-client jar files.
Need to mount a volume to “/home/mosip/build_files” with below files
logback.xml
Client.crt : Signer certificate to be added in the registration-client build for jar sign verification.
keystore.p12 : Store private key used to sign the registation-client and registration-services jar files with “CodeSigning” alias.
maven.metadata.xml : Holds the current version of registration-client hosted in the upgrade server.
Optional
reg_client_custom_impls_url_env
: URL to download scanner custom implementation jars(runtime dependency).
Finally, you can download the registration client zip from below URL. {registratiionclient download server domain name/ip}/registration-client/{client_version}/reg-client.zip}
References
Run (https://github.com/mosip/mosip-infra/blob/develop/deployment/v3/mosip/regclient/create-signing-certs.sh) to generate Client.crt
and keystore.p12
.
To get the content of maven-metadata.xml
and logback.xml
check (https://github.com/mosip/mosip-helm/blob/develop/charts/regclient/templates/configmap.yaml)
Clicking on in the home page opens a pop-up displaying configured Settings page as per the above sample settings schema.
The Tus protocol
is designed to enable resumable uploads of large files over HTTP, which can be useful for web applications that need to handle file uploads in unreliable network conditions or with large files that might take a long time to upload. For more information on TUS, refer .
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.
For the code setup, clone the repository and follow the guidelines mentioned in the .
1. For the environment setup, you need an external dependency that is available with different versions. (E.g.: You can download mock-sdk.jar
and add to registration-services project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
3. Download openjfx-11.0.2_windows-x64_bin-sdk.zip
from , unzip and place it in your local file system. This folder contains list of javafx related jars that are necessary for running Registration Client UI.
Dockerfile is available under .
Note: The change in nomenclature from 'Print Stage' to 'Credential Requestor Stage' was implemented to enhance clarity and better reflect its expanded functionality.
In MOSIP 0.9.0, the "print stage" was primarily designed to facilitate the submission of printing requests. The core functionality of print stage revolved around initiating a request for the physical printing of credentials. However, as the system evolved and incorporated additional features, the scope of the print stage expanded beyond its original purpose.
In the evolved approach, at the print stage, apart from processing a print request, the application enables partner-specific print capabilities. Contrary to its initial purpose, the print stage no longer serves the singular function of printing credentials. Instead, it has transformed into a multifaceted component with enhanced set of responsibilities.
In the current system, the print stage's role extends beyond traditional printing activities. Its primary function now revolves around initiating a request for credential generation once a Unique Identification Number (UIN) is generated. This request is not aimed at physical printing but serves as a mechanism to gather additional information for specific partners. These partners may require supplementary data beyond what is initially generated with the UIN.
Therefore, in the evolved approach, the print stage has transitioned from being a straightforward printing request to a more versatile component that manages the initiation of credential requests tailored to partner-specific information needs. This adaptation reflects the system's responsiveness to changing requirements and the dynamic nature of credentialing processes. This reason led us to re-name the “Print Stage” to the “Credential Requestor Stage” as this name serves the purpose of the work executed by this stage.
The Credential Requestor Stage in MOSIP, formerly known as the Print Stage, is a crucial component used to request credentials for configurable partners after the UIN is generated. This stage enables countries to share information with multiple partners, each with specific needs after UIN generation. Partners, such as Print Partners and Digital Card Partners, may require demographic or biometric information to perform operations.
The Credential Requestor Stage plays a crucial role in the MOSIP system, serving as a mechanism to solicit credentials from configurable partners post-UIN generation. In this context, partners, previously registered with MOSIP, require demographic and biometric data to execute their respective operations. For instance, a Print Partner necessitates specific demographic details for the purpose of printing cards. Similarly, digital card partners seek demographic information to generate digital cards. Additionally, DPGs might seek confirmation of successful UIN generation to integrate this information into their systems. The Credential Requestor Stage facilitates various use cases where the country aims to share pertinent information with multiple partners subsequent to UIN generation.
MOSIP has introduced a new partner profile for the Credential Requestor Stage. The partner profiles are maintained here.
Sample Partner Profile:
Field Description
id
: Logical unique identifier
partnerId
: Partner identifier configured in MOSIP
credentialType
: Type of credential configured in MOSIP
template
: Template used for generating the credential
appIdBasedCredentialIdSuffix
: Applicable for special conditions where the credential ID is the application ID itself, with an optional suffix (for example, .pdf
). Currently, this is applicable for digital card credentials.
process
: If applicable for a particular process. If applicable for all processes, value is null
metaInfoFields
: Meta information fields to be sent as additional information while generating the credential
Configuration Changes
Once the partner profile is configured, the System Integrator (SI) should make changes to the following configurations:
mosip.registration.processor.credential.partner-profiles
: Specify the file name for the partner profiles. By default its → registration-processor-credential-partners.json
. If a country intends to change the file name only then this configuration should be updated otherwise default configuration can be used
mosip.registration.processor.credential.default.partner-ids
: Specify default partner IDs for which credentials will be created automatically
mosip.registration.processor.credential.conditional.partner-id-map
: Define conditions for conditional partners. Credentials for these partners will be requested only if the conditions are met. Use MVEL
expressions for conditions
mosip.registration.processor.credential.conditional.no-match-partner-ids
: Specify a partner ID to be used when no conditions are met for conditional partners
Conditional Partner Requests
The stage will create credentials for default partner IDs by default
For conditional partners, credentials will be requested only if they match a particular MVEL
expression
MVEL
expressions can be written on any identity field as well as meta info field
If there is no condition match for conditional partners, SI can configure a no-match partner, which will be used when no conditional partner match is found
Configuration File Locations
Credential Requestor Stage Configuration: Click here to view credential requestor stage configuration details.
Partner Profile Configuration: Click here to view partner profile configuration details.
The Credential Requestor Stage configuration is an essential part of MOSIP's functionality, enabling seamless communication with partners and ensuring the secure exchange of information post-UIN generation.
Note: Ensure that configured IDs are logically unique and consistent across future configurations.
Registration Processor (Regproc) is a backend processing engine to enable the ID Lifecycle management. The diagram below shows the Registration Processor along with the other modules that contribute in issuing a Unique Identification Number(UIN) for an individual. Internally, Regproc follows the SEDA architecture where data flows via multiple stages till the UIN is issued.
The relationship of Regproc with other services is explained here. NOTE: The numbers do not signify sequence of operations or control flow
Registration packets are uploaded by Registration Client to Packet Receiver.
After packet validation is done Regproc notifies pre-registration application using datasync service.
Quality of biometrics is checked using an external biometric SDK. This is done in Regproc's Quality Classifier stage.
The above data is shared by providing a URL that partners use to fetch data. This URL is obtained from Datashare service.
Regproc's ABIS Middleware stage communicates with ABIS via Activemq. The ABIS performs deduplication and sends back result to the Queue.
Regproc stores and updates applicant demographic and biometric information in ID Repository. Also Activates or deactivates applicant UIN.
Regproc calls IDA Internal Authentication Service to authenticate Applicant(for update flow), introducer, operator and supervisor(when bio auth mode is used to create packet).
After the UIN is processed the Printing Stage calls Credential Service to create credential for print. This credential will be pushed to websub and the Printing systems will consume same.
The Notification Service is used to send email/sms notification to the applicant after the request processing is completed in server.
Regproc connects to external "Manual Adjudication System" via queue. Regproc sends applicant information required for adjudication in queue and external adjudication system consumes it. The data is shared from mosip to external adjudication system based on policy.
Regproc calls Key Manager for decrypting packet and for encrypting information.
Regproc uses Masterdata Service to validate center, machine, user etc.
Regproc connects to Virus Scanner for scanning packets in Packet Receiver Stage and Packet Uploader Stage
Each Stage in regproc calls Packet Manager to read information from packet.
The Registration Processor contains several stages and services.
The registration packet flows through the various stages depending on the type of flow. See Registration Flows and Stage Sequence.
Note: The Print Stage has been renamed as the Credential Requestor Stage. For further information, please click here.
Refer to repo.
Refer to Configuration Guide.
To know more about the developer setup, read Registration Processor Developers Guide.
Refer API Documentation.
Registration Processor(Regproc) is a backend processing engine to enable the ID Lifecycle management. It has several stages and services, registration packet flows through various stages depending on the type of flow.
The documentation here will guide you through the prerequisites required for the developer's setup.
Below are a list of tools required in Registration Processor:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up Registration Processor on your local system:
1. Download lombok.jar
and settings.xml
from here.
2. Unzip Apache Maven and move the unzipped folder in C:\Program Files
and settings.xml
to conf
folder C:\Program Files\apache-maven-3.8.4\conf
.
3. Install Eclipse, open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
.
4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you don't have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
For the code setup, clone the registration repository from and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
2. Clone mosip-config repository.
3. Create an empty folder inside the mosip-config
with sandbox-local
name and then copy and paste all the config files inside sandbox-local
folder except .gitignore, README and LICENSE
.
4. As Registration Processor is using two properties files, registration-processor-default
and application-default
, you will have to configure them according to your environment. The same files are available here for reference.
5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.
6. Put both the files in the same folder and change the location attribute to sandbox-local
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar
.
7. Run the server by opening the config-server-start.bat
file.
The server should now be up and running.
8. Before running any application of Registration Processor, replace the below properties in bootstrap.properties
:
spring.cloud.config.uri=http://localhost:51000/config
spring.cloud.config.label=master
spring.profiles.active=default
spring.profiles.active can be dmz or mz(default)
9. An alternative approach to start the application is to place the dependency of application to be executed in the pom of MOSIP stage executor
update maven and place above mentioned properties in the bootstrap.properties
and then start MOSIP stage executor
.
When biometric duplicates are found in ABIS, the MOSIP system sends a request for manual adjudication to the Manual Adjudication System via a queue.
The system integrator can build the Manual Adjudication System, which would be listening to the MOSIP-to-ManualAdjudication
queue for any manual adjudication requests and sends a response back in the ManualAdjudication-to-MOSIP
system after verifying the data.
The data sent to the Manual Adjudication System is driven by a policy defined in MOSIP and the specification is similar to ABIS identify request.
Sends the applicant's demographic and biometric information (via queue + Datashare) to Manual Adjudication System (MAS).
Receives decision from MAS and accordingly forwards the packets.
If rejected, notifies the applicant.
requestId
: request_id that is associated with each request present in reg_manual_verification
table.
referenceId
: reg_id that is associated with each request present in reg_manual_verification
table.
referenceURL
: Datashare url of biometrics, demographics(identity), audits, metainfo, documents of reg_id
gallery
: contains the matched ref_id and referenceURL of matched ref_id.
returnValue
: 1-Success, 2-Failure
candidateList
: It contains matched candidate referenceIds, count and analytics.
Datashare contains biometrics, identity documents, metainfo, audits related to particular rid and the datashare URL contains encrypted form of this data.
Note: Datashare encryption using partner key and decryption in MAS is using private key of that partner.
GET https://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD
The structure of the encrypted data downloaded from referenceURL in MOSIP 1.2.0 or later versions. The data downloaded would be URL-safe base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two parts after splitting using #KEY_SPLITTER#.
Block 1:
Block 1, i.e. the encrypted key data is again split into three parts, • The 1st part is VER_BYTES (version bytes). The Current version constant is set as VER_R2 and this is present in the first 6 bytes of Block 1.
• The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.
• The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.
Block 2:
Block 2, i.e. the encrypted actual data is again split into two parts,
• The 1st part is the random 32 bytes which will be used as AAD in AES encryption (first 32 bytes). From this 32 bytes AAD data, the first 12 bytes is IV/Nonce.
• The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.
The structure of the encrypted data downloaded from referenceURL in MOSIP 1.1.5.5 or prior versions.
The data downloaded would be base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two parts after splitting using #KEY_SPLITTER#.
Block 1:
Block 1, i.e. the encrypted key data is again split into two parts,
The first part is the Certificate Thumbprint i.e. the key identifier which is the first 32 bytes in Block 1.
The second part is the Encrypted Random AES Key which is encrypted with RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.
Block 2:
Block 2, i.e. the encrypted actual data is again split into two parts,
The 1st part is the Encrypted data, encrypted using AES GCM PKCS5Padding.
The 2nd part is IV/Nonce i.e. the last 32 bytes appended after encrypted data.
partner Id
: mpartner-default-adjudication
policy Id
: mpolicy-default-adjudication
In registration-processor-default.properties
, the possible Error codes are as follows:
This stage is applicable only if required biometrics are not present in the packet as per country configuration.
Sends applicant's demographic documents (via Queue + Datashare) to external Verification System (VS).
Receives decision from VS and accordingly forwards the packets.
If rejected, notifies the applicant.
requestId
: verification_request_id that is associated with each request present in reg_verification table
.
referenceId
: reg_id that is associated with each request present in reg_verification
table.
referenceURL
: Datashare URL of biometrics, demographics(identity) ,audits, metainfo, documents of reg_id .
Response parameters
returnValue
: 1-success, 2-failure
Datashare contains biometrics, identity, documents, metainfo, audits related to particular rid
and datashare URL contains encrypted form of this data.
Note: Datashare encryption using partner key and decryption in MAS is using private key of that partner.
GET https://datashare-service/v1/datashare/get/mpolicy-default-adjudication/mpartner-default-adjudication/mpartner-default-adjudicationmpolicy-default-adjudication202011110619201EpLEjvD
The structure of the encrypted data downloaded from referenceURL in MOSIP 1.2.0 or later versions. The data downloaded would be URL-safe base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two parts after splitting using #KEY_SPLITTER#.
Block 1:
Block 1, i.e. the encrypted key data is again split into three parts, • The 1st part is VER_BYTES (version bytes). The Current version constant is set as VER_R2 and this is present in the first 6 bytes of Block 1.
• The 2nd part is the Certificate Thumbprint i.e. the key identifier which is present in the next 32 bytes after VER_BYTES.
• The 3rd part is the Encrypted Random AES Key, encrypted with the RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.
Block 2:
Block 2, i.e. the encrypted actual data is again split into two parts,
• The 1st part is the random 32 bytes which will be used as AAD in AES encryption (first 32 bytes). From this 32 bytes AAD data, the first 12 bytes is IV/Nonce.
• The 2nd part is the encrypted data which is encrypted using AES GCM PKCS5Padding.
The structure of the encrypted data downloaded from referenceURL in MOSIP 1.1.5.5 or prior versions.
The data downloaded would be base64 encoded. Hence, after decoding the data will be in the below format. It will be divided into two parts after splitting using #KEY_SPLITTER#.
Block 1:
Block 1, i.e. the encrypted key data is again split into two parts,
The first part is the Certificate Thumbprint i.e. the key identifier which is the first 32 bytes in Block 1.
The second part is the Encrypted Random AES Key which is encrypted with RSA OAEP - SHA256-MFG1. This constitutes the remaining 256 bytes of Block 1.
Block 2:
Block 2, i.e. the encrypted actual data is again split into two parts,
The 1st part is the Encrypted data, encrypted using AES GCM PKCS5Padding.
The 2nd part is IV/Nonce i.e. the last 32 bytes appended after encrypted data.
Possible Error codes and Messages from Datashare URL
partner Id
: mpartner-default-adjudication policy Id
: mpolicy-default-adjudication
The manual adjudication stage in performs the following functions:
Encrypted Key Data | KEY_SPLITTER | Encrypted Actual Data |
---|
Encrypted Key Data | KEY_SPLITTER | Encrypted Actual Data |
---|
Error Code | Error Message |
---|
Error Code | Error Message |
---|
Encrypted Key Data | KEY_SPLITTER | Encrypted Actual Data |
---|
Encrypted Key Data | KEY_SPLITTER | Encrypted Actual Data |
---|
Error Code | Error Message |
---|
Error Code | Error Message |
---|
Block 1 | #KEY_SPLITTER# | Block 2 |
Block 1 | #KEY_SPLITTER# | Block 2 |
DAT-SER-003 | File does not exist or File is empty |
DAT-SER-006 | Data share not found |
DAT-SER-006 | Data share usage expired |
KER-ATH-401 | Authentication failed |
KER-ATH-403 | Forbidden |
RPR-MVS-000 | manual verification failed |
RPR-MVS-001 | Registration Id should not empty or null |
RPR-MVS-002 | No matched reference id found for given RID |
RPR-MVS-025 | Manual adjudication failed |
RPR-MVS-022 | Registration Id should not empty or null |
RPR-MVS-022 |
|
RPR-MVS-021 | Manual verification rejected |
RPR-MVS-025 | Manual verification resend to queue |
RPR-SYS-012 | IO EXCEPTION |
Block 1 | #KEY_SPLITTER# | Block 2 |
Block 1 | #KEY_SPLITTER# | Block 2 |
DAT-SER-003 | File does not exists or File is empty |
DAT-SER-006 | Data share not found |
DAT-SER-006 | Data share usage expired |
KER-ATH-401 | Authentication Failed |
KER-ATH-403 | Forbidden |
RPR-MVS-004 | No Assigned Record Found |
RPR-MVS-025 | Multiple rids found for a reference id |
RPR-MVS-022 | TablenotAccessibleException in Manual verification |
RPR-VER-002 | Verification failed |
RPR-VER-004 | Resend for verification |
RPR-MVS-016 | Reg Id should not be null or empty |
RPR-MVS-021 | Manual verification rejected |
This repository contains the UI code for Resident portal. To know more about the features and functions present on the portal, refer here.
Note: The code is written in Angular JS.
Install node.js
- To build the angular code using angular cli that runs on node, recommended Node: 14.17.3, Package Manager: npm 6.14.13
Install angular cli
– To install angular cli for building the code into deployable artifacts. Follow the following steps to install angular cli on your system.
npm install -g @angular/cli
(to install angular cli)
ng --version
(to verify angular is installed in system) We recommend Angular CLI: 13.3.2
Check out the source code from GIT – To download the source code from git, follow the steps below to download source code on your local system.
git clone https://github.com/mosip/resident-ui.git (to clone the source code repository from git)
Build the code
Follow the steps below to build the source code on your system.
Navigate to the resident-ui directory inside the cloned repository.
Run the command ng build "--prod" "--base-href" "." "--output-path=dist"
in that directory to build the code.
Build Docker image
Follow the steps below to build the docker image on your system.
docker build -t name .
(replace name
with the name of the image you want, "." signifies the current directory from where the docker file has to be read.)
Example: docker build -t residentui .
Run the Docker image
Follow the steps to build docker image on your system.
docker run –d –p 80:80 --name container-name image-name
(to run the docker image created with the previous step,-d
signifies to run the container in detached mode, -p
signifies the port mapping left side of the":" is the external port that will be exposed to the outside world and right side is the internal port of the container that is mapped with the external port. Replace container-name
with the name of your choice for the container, replace image-name
with the name of the image specified in the previous step)
Example: docker run -d -p 8080:8080 --name nginx residentui
Now you can access the user interface over the internet via browser.
Example: http://localhost:8080/#/dashboard
Build & deploy the code locally
Follow the steps below to build the source code on your system.
Navigate to the resident-ui directory inside the cloned repository. Then, run the following command in that directory:
npm install
ng serve
Now, you can access the user interface via browser.
Example: http://localhost:4200
The provided guide presents a list of essential properties that can be customised according to a specific installation. Please note that this list is not exhaustive but rather acts as a checklist to review properties that are expected to differ from their default settings. If you require access to all properties, please refer to the files mentioned below.
Resident Service uses the following configuration files:
Properties used for configuring the database.
These are the authentication types allowed for a resident and default unlock duration.
Templates type codes for authentication types:
Below are the properties used for validation purpose:
Property used to get the identity mapping json
Properties used for machine specification and center:
This is an exclusion list of URL patterns that should not be a part of authentication and authorization.
Properties used to define the endpoints that should not be part of authentication.
These properties (comma separated values) are used to define the keys of the properties to be exposed to UI.
This property will directly apply the certs URL without the need for constructing the path from issuer URL. This is useful for keeping different certs URL for integrating with MOSIP e-Signet for offline token validation.
Used in open-id-connect
based login with UIN/VID in MOSIP e-Signet(IDP)
Used for login purpose:
Properties used to define application and reference id.
For Minio: object.store.s3.url=http://minio.minio:9000
For AWS: object.store.s3.url=s3.${s3.region}.amazonaws.com
Property used to enable virus scanner flag
Property used to get the vid policy json:
Property used to get the UI schema json
This property is used to get the data format from MVEL file:
Below websub properties are used for authentication type status event:
Below websub properties used for authentication transaction status event:
Below websub properties used for credential status event:
Properties used to get the data format from MVEL file.
The Registration centers will be searched based on the distance value in meters from the Geo location identified
Configure Time limit for OTP Flooding scenario (in minutes).
Define property name in below format-
resident..template.property.attribute.list
Commenting or removing this property will disable reference validator.
For validating request time as per before and after time limit (in seconds) in contact-details/update API.
The java.time.format.FormatStyle enum to use for date time formatting based on locale. Allowed values with examples are:
FULL ('Tuesday, April 12, 1952 AD' or '3:30:42pm PST')
LONG('January 12, 1952')
MEDIUM ('Jan 12, 1952')
SHORT ('12.13.52' or '3:30pm')
Current value is MEDUIM. For more details refer to the enum.
URL pattern for logging filter. For example, "/callback/" .Defaults to "/".
This will print the request details such as URL, headers and body for debugging purpose. Default is false.
Resident Services are the self-services which are used by the residents themselves via a portal. Resident Portal is a web based UI application that provides residents of a country the services related to their Unique Identification Number (UIN).
The documentation here will guide you through the pre-requisites required for the developer' setup.
Below are a list of tools required in Resident Services:
JDK 11
Any IDE (like Eclipse, IntelliJ IDEA)
Apache Maven (zip folder)
pgAdmin
Postman
Git
Notepad++ (optional)
lombok.jar (file)
settings.xml (document)
Follow the steps below to set up Resident Services on your local system:
Download lombok.jar
and settings.xml
from here.
Install Apache Maven.
Copy the settings.xml
to ".m2" folder C:\Users\<username>\.m2
.
Install Eclipse.
Open the lombok.jar
file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update
. Specify the eclipse installation location if required by clicking the ‘Specify location…’ button. Then, click Install/Update
button to proceed.
Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse
to see if the lombok.jar
is added. By doing this, you will not have to add the dependency of lombok
in your pom.xml
file separately as it is auto-configured by Eclipse.
Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs
.
For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.
Open the project folder where pom.xml
is present.
Open command prompt from the same folder.
Run the command mvn clean install -Dgpg.skip=true -DskipTests=true
to build the project and wait for the build to complete successfully.
After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish
.
After successful importing of project, update the project by right-click on Project → Maven → Update Project
.
For the environment setup, you need an external JAR that is available here with different versions. Download below mentioned JARs with appropriate latest/appropriate versions. You will need to input appropriate artifact id and version and other inputs.
a. icu4j.jar
b. kernel-auth-adapter.jar
c. kernel-ref-idobjectvalidator.jar
d. kernel-transliteration-icu4j.jar
For e.g.: You can download kernel-auth-adapter.jar
and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close
).
Clone mosip-config repository.
a. As Resident Services is using two properties files- resident-default.properties
and application-default.properties
. But for local running of the application, you need to provide additional/overriding properties such as secrets, passwords and properties passed by the environment which can be added in new files application-dev-default.properties
(common properties for all modules) and resident-dev-default.properties
(Resident service specific properties).
b. You will have to create both the property files according to your environment and put them in mosip-config folder
(cloned). The same files are available below for reference.
These two files are loaded by application by specifying the application names in the Application VM arguments like- Dspring.cloud.config.name=application,resident,application-dev
, resident-dev
(also detailed in later section).
To run the server, two files are required- kernel-config-server.jar
and config-server-start.bat
.
Put both the files in the same folder and point the property- Dspring.cloud.config.server.native.search-locations
to mosip-config
folder in config-server-start.bat
file and also check the version of kernel-config-server.jar
towards the end of the command.
Example:
As mentioned earlier, you will have to create property files according to your environment like resident-env-default
and application-env-default
(here env represents environment name). Both files will contain different configurations such as resident-env-default
will have config properties (e.g., secrets, passcodes, etc) used for resident-services module only and application-env-default
is used for environment specific changes and can be used for other modules as well.
In this example, currently, these two files are created for dev environment and hence the files have suffix of -dev
. If you want to run it for a different environment such as qa, create these two files with -qa
suffix and then you will also need to provide the appropriate VM argument for that referring to qa environment.
For instance,
Add mosip.resident.client.secret=***********
property to be able to use a decrypted passcode and run it in your local machine.
If you check the URLs present in application-default
file, they are set to module specific URLs, but you need to use internal/external environment URLs to access the APIs by using application-dev-default file.
In application-dev-default
file, assign environment domain URL to mosipbox.public.url
and change all other URLs with ${mosipbox.public.url}.
It results in mosipbox.public.url=internal/externalAPI
(e.g., mosipbox.public.url=https://api-internal.dev.mosip.net) and it will connect with the Development environment.
Run the server by opening the config-server-start.bat
file.
Open Eclipse and run the project for one time as Java application, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Resident-dev").
Open the Arguments tab and specify Application VM arguments: For example, for dev environment:
Save this run configuration as ‘Resident-dev’ .
For qa
environment, you can create Resident-qa
run configuration with VM argument as below.
Example:
Click Apply
and then debug it (starts running). In the console, you can see a message like Started ResidentBootApplication in 34.078 seconds (JVM running for 38.361)
.
For API documentation, refer here.
The APIs can be tested with the help of Postman or Swagger-UI.
Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster. It is widely used tool for API testing. Below you will find the APIs postman collection of resident-services.
Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of resident-services for dev-environment from https://api-internal.dev.mosip.net/resident/v1/swagger-ui.html
and localhost from http://localhost:8099/resident/v1/swagger-ui.html
.
Download the JSON collection available below and import in your postman. Resident-Service-APIs.postman_collection-latest.json.
Create an environment as shown in the image below.
This environment is created for dev. Give the variable name as url
and set both the values as https://api-internal.dev.mosip.net
.
In the similar way, create another environment as shown below.
This environment is created for localhost. Give the variable name as url
and set both the values as http://localhost:8099
.
MOSIP provides a reporting framework for real-time streaming of data and visualization. The dashboards give a visual display of metrics and important data to track the status of various pre and post-enrollment processes. This data helps ID issuers with improving efficiency, forecasting, and better decision-making. The framework has been used to create a set of default dashboards using Kibana.
Details of reporting framework can be found here.
The following dashboards are configured on Kibana. The NDJSON source files are available here.
The reporting pipeline and dashboards may be customized according to an adopter's requirements.
Setup a data pipeline for populating data from database to Elasticsearch as given here.
After data is populated in Elasticsearch, add/customize dashboards in Kibana as given here.
Resident services are the self-services which are used by the residents themselves via a portal. Resident Portal is a web-based UI application that provides residents of a country the services related to their Unique Identification Number (UIN). The residents can perform various operations related to their UIN/ VID and can also raise concerns if any through the portal.
The key features provided on the Resident portal are:
Avail UIN services using UIN/ VID (through e-Signet):
View My History
Manage My VID
Secure My ID
Track My Requests
Get Personalised Card
Share My Data
Logout
Get Information
About Registration Centers
List of supporting documents
Get My UIN (using UIN/ VID/ AID)
Verify email ID and/ or phone number
Responsive UI support- Support for the application to work seamlessly on various resolutions.
Book an appointment for new enrolment (via the pre-registration portal)
Ancillary features
Font size
Get Notifications (email and bell notifications)
View profile details of the logged in user (name, photo, and last login details)
Below is an image summarizing the features provided in Resident portal.
The relationship of Resident services with other services is listed below.
Note: The numbers do not signify sequence of operations or the control flow.
Audit Manager: Resident services sends all the audit logs to the Audit Manager.
Digital card service: Resident services uses this service to download the PDF of the UIN card or VID card.
Credential Request Generator Service: This service is used to share the credential with various partners like print partners, authentication partners, and digital card partners.
ID Repository Identity Service: Resident services uses this service to retrieve the identity information of a credential and to lock/unlock authentication types.
ID Repository VID service: This service is used to generate/revoke various types of VIDs.
ID Authentication: This service is used by Resident services to authenticate users.
MOSIP e-Signet: This is used to authenticate and authorize the users in an event of login using UIN/ VID.
Resident UI: This is the interface through which users can interact with the Resident services.
WebSub: This is used to get asynchronous notification from IDA for acknowledgment purposes.
Registration Processor: This is used to sync and upload packets for features pertaining to changes in identity data.
Packet Manager: Resident services uses this service to create packets.
Partner Management Service: Resident services uses this service to get information about various partners and policies.
Keycloak: Resident services uses this to authenticate in order to access the MOSIP internal APIs. The Resident services communicates with endpoints of other MOSIP modules via a token obtained from Keycloak.
Master data service: Resident services invokes the Master Data services to get various templates and machine details.
Notification service: Resident services uses this service to send various notifications through email or SMS.
Key Manager: Resident services uses Key Manager to encrypt or decrypt the data used across features.
The design of the Resident portal embodies the following principles:
One-stop solution: The Resident portal is designed to have components that aims to solve all the queries, issues, or discrepancies of the residents and acts as a one-stop solution for all the requirements.
Self-Sovereign: Once the ID is issued by an authority, the user/resident/citizen chooses to control and manage their data in their choice of devices.
Inclusive: The Resident portal aims to be available in all the browsers while also catering to the needs of visually impaired, dyslexic and colour-blind folks.
Presence assurance: This web-based UI application would put in all its efforts to ensure easy access to all the residents with high availability.
Works Remote: The Resident portal should be able to share credentials when data needs to be shared remotely without physical presence.
Trusted: The identity verification process on the device should be trusted so that it can be used in service delivery without any concerns.
Grievance redressal: The Resident portal ensures that in case of any concerns or grievance, the issue is raised and resolved through the portal itself.
This guide contains all the information required for successful deployment and running of Resident Portal. It includes information about the Database and template scripts, seed data, roles, OIDC client setup, etc.
mosip-resident-client
needs to have below roles in keycloak:
RESIDENT
SUBSCRIBE_AUTH_TYPE_STATUS_UPDATE_ACK_GENERAL
SUBSCRIBE_AUTHENTICATION_TRANSACTION_STATUS_GENERAL
SUBSCRIBE_CREDENTIAL_STATUS_UPDATE_GENERAL
CREDENTIAL_REQUEST
Below are the steps to create the Resident OIDC client as standard steps in DevOps after e-Signet and Resident deployment.
Have a user created in keycloak with the below roles as needed for the Authorization token in the API requests:
i. ZONAL_ADMIN,
ii. PARTNER_ADMIN,
iii. POLICY_MANAGER,
iv. MISP_PARTNER,
v. PMS_ADMIN
Authenticating user to take the token and use it in all APIs invoked in further steps:
Swagger URL - https://api-internal.dev2.mosip.net/v1/authmanager/swagger-ui/index.html?configUrl=/v1/authmanager/v3/api-docs/swagger-config#/authmanager/getAllAuthTokens
Request Body:
Step 1: Creating a policy group for resident OIDC Client
Note: Since policymanager service swagger does not work, you can use postman for APIs in it.
POST - https://api-internal.dev2.mosip.net/v1/policymanager/policies/group/new
Request Body:
Make note of the prolicyGroupId
from the response.
Step 2: Creating a policy for Resident OIDC client
POST - https://api-internal.dev2.mosip.net/v1/policymanager/policies
Request Body:
Step 3: Publishing policy
POST - https://api-internal.dev2.mosip.net/v1/policymanager/policies/{{policyId}}/group/{{policyGroupId}}/publish Path params: * policyId
- resident-oidc-client-policy * policyGroupId
- from previous response
Step 4: Resident OIDC Client Partner self registration
Swagger URL: https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/partnerSelfRegistration
Request Body:
Step 5: Upload ROOT Certificate as CA certificate
i. Get certificate from keymanager with below parameters:
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "ROOT", refID: ""
ii. Uploaded it as CA certificate:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/uploadCACertificate
Request Body (Example only):
Step 6: Upload RESIDENT certificate as CA certificate
i. Get certificate from keymanager with below parameters:
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "RESIDENT", refID: ""
ii. Uploaded it as CA certificate:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/uploadCACertificate
Request Body (Example only):
Step 7: Upload RESIDENT : IDP_USER_INFO
certificate as Partner certificate
i. Get certificate from keymanager with below parameters:
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "RESIDENT", refID: "IDP_USER_INFO"
ii. Uploaded it as Partner certificate:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/uploadPartnerCertificate
Request Body (Example only):
Step 8: Create policy Mapping request:
Swagger URL: https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/partner-service-controller/mapPolicyToPartner
Path param:
partnerId
: resident-oidc-client-partner
Request Body:
Output:
Make not of the mappingKey
.
Step 9: Approve policy mapping:
Swagger URL - https://api-internal.dev2.mosip.net/v1/partnermanager/partners/policy/{{mapping key}}
Note: This mapping key will be returned as an output from policy mapping request.
Request Body:
Step 1: Prepare the RESIDENT JWKS public key JSON.
i. Get certificate from keymanager with below parameters
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getCertificate
AppID: "RESIDENT", refID: ""
ii. Store the certificate as resident-oidc.cer
file. Make sure to replace chars with line breaks and save it*
iii. Get the KeyID of the above certificate using Get All Certificates API
Swagger URL: https://api-internal.dev2.mosip.net/v1/keymanager/swagger-ui/index.html?configUrl=/v1/keymanager/v3/api-docs/swagger-config#/keymanager/getAllCertificates
AppID: "RESIDENT", refID: ""
From the response get the keyId
. This will be the kid
attribute in the OIDC client creation step.
iv. Get JWKS public key JSON from certificate
Use the certpem2jwksjson.jar
with below command to get the JWKS of that. (Attached the Java code of that for creating automted step of this)
In the console, the JSON text of the public key of the certificate will be printed. Copy it.
v. Correct the kid
in JWKS public key JSON
In the JSON public key, replace the kid
value with the keyId
in the earlier step.
Step 2: Create the OIDC client in PMS
Swagger URL: https://api-internal.dev2.mosip.net/v1/partnermanager/swagger-ui/index.html?configUrl=/v1/partnermanager/v3/api-docs/swagger-config#/client-management-controller/createClient
In the request body, make sure to replace thebelow attributes:
publicKey
- the JWKS public key JSON from earlier step
logoUri
- Correct hostname for the Resident UI
redirectUris
- Correct the hostname for Resident Service
Request Body (Example only):
The response will contain the Resident OIDC client ID in clientId
attribute.
Step 3: Configure the Resident OIDC client in resident-default.properties
.
Configure the above obtained Resident OIDC client ID resident-default.properties
with property name mosip.iam.module.clientID
.
Note: This will need a restart of the resident service if it is already deployed.
The Resident Portal is a user-friendly web-based platform designed to assist residents in accessing various services associated with their Unique Identification Number (UIN). This portal offers a range of essential services such as:
View My History
Manage My VID
Secure My ID
Track My Requests
Get Personalised Card
Share My Data
Logout
Get Information
About Registration Centers
List of supporting documents
Get My UIN (using UIN/ VID/ AID)
Verify email ID and/ or phone number
Responsive UI support- Support for the application to work seamlessly on various resolutions.
Book an appointment for new enrolment (via the pre-registration portal)
Ancillary features
Font size
Get Notifications (email and bell notifications)
View profile details of the logged in user (name, photo, and last login details)
Below is the detailed explanation of each of the features mentioned above.
Residents can use these services to view, update, change, manage or share their data. They can also report an issue in case of a grievance.
Pre-requisites: To login into the Resident Portal, the resident should have their unique virtual ID (VID) or Unique Identification Number (UIN) and also have access to the registered email ID/ phone number to be able to receive the OTP.
Resident accesses the Resident Portal dashboard page.
Resident clicks on UIN Services
.
The login screen appears and the resident can choose one of the options to log in.
To login with OTP authentication, the resident clicks on Log in here> More ways to login > Login with OTP
.
Resident needs to enter valid VID in the Enter Your VID
text field and check the box I'm not a robot
.
Next, the resident clicks on the Get OTP
button.
The resident receives the OTP on the registered phone number and email ID.
The resident needs to enter the valid OTP received within stipulated time and click the Verify
button.
The resident is then navigated to the Consent page. On this page, the Essential and Voluntary claims are displayed. Additionally, they will also have to allow access to their data in Authorize Scope section to avail various services. Based on the consent provided by the resident, the services will be made available for modification.
The resident has the choice to select from the list of Voluntary claims while the Essential claims are mandatory.
The resident should now click the Continue
button. The system navigates the resident to the UIN Services menu page from where they can avail various services.
Note: Consent page will be available only for first time login.
The residents can view the history of all the transactions associated with their logged-in UIN/ VID. They can also view their details and if any unaccounted entry is found, a report can be raised against the same.
The residents can perform the following:
Search: The residents can enter an Event ID to search a particular event.
Filter based on date (From date and To date): The Residents can put a “from” and “to” date in order to get the list of all the events performed in the chosen date range.
Filter based on status (Success/ In Progress/ Failure): The Residents can filter based on the status of the event. E.g.: If they want to view all “In Progress” events, they can choose the status as “In Progress”. Additionally, they can also select any combination of the above three options.
Filter based on History Type (Authentication, ID Management, Data Update, Data Share, Service Requests): The Residents can filter based on the type of event. Additionally, they can also choose any combination of the above five options.
Authentication Request: This includes all the authentication and e-KYC requests.
ID Management Request: This includes the below services:
Manage My VID (Generate/Revoke VID)
Verify phone number/email ID
Secure My ID (Lock/unlock various authentication types)
Data Update Request: This includes the below services:
Update my UIN (demographic data and contact data)
Data Share Request: This includes the below services:
Share with a partner
Service Request: This includes the below services:
Download configured card
Physical card
Get my UIN
Book an appointment (lost UIN, Update UIN, Pre-registration, other)
Go button: Residents can click on the Go
button once they are done selecting all the required filters.
Download the PDF of the results: The residents can download the PDF version of the search result populated.
Clicking on the accordion/ the caret of a particular event, the following options will appear:
a. View Details: The residents can view the details about an event by clicking on View Details
. They will be redirected to Track My Request
page with pre-filled EID where they can see further details about the event.
b. Pin Event to the top: The residents can pin the events to the top of the list based on their preference. Currently, this is configured for up to 3 events but it can be customized as per country’s requirements. Also, the resident can unpin the pinned events by clicking Unpin from Top
.
c. Report a grievance: The residents can report a grievance in case of fraud or for any event not initiated by them. On clicking Report an Issue
, the resident will be redirected to the Grievance Redressal Form
page where they will see a set of pre-filled data as well as a set of data to be filled.
Pre-filled data:
Name
Event ID (EID)
Registered Email ID
Registered Mobile Number
Data to be filled:
Alternate Email ID
Alternate Mobile Number
Comments
Once the event is completed, a message is displayed containing the grievance tracking ID.
Below are the images with different filters on this page.
On clicking Manage My VID
, the resident will be taken to a page where they can view details of the existing VIDs, generate new VID, revoke existing VID or download a VID card.
The following types of VIDs can be seen based on the VID policy:
Perpetual VID
Temporary VID
One-time VID
Note: The resident can get to know about the features of a particular VID by hovering over the “i” symbol.
The residents can perform the following:
Create a new VID : The residents can click on the Create
button against any of the VID type selected. They can click on Yes
to proceed. Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
Revoke an existing VID: The residents can click on the Delete icon to revoke an existing VID. They can click on Yes
to proceed. Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
Download a VID card:
a. The residents can click on the Download icon to initiate the download process. They can click on Download
to proceed. Once the event is completed, a message is displayed containing the Event ID, a link to track the service and the password combination.
b. Once the card is ready to download, they will receive a notification for the same under the bell icon displayed on the top right corner of the screen and as an Email notification.
c. On clicking on the notification, the resident will be taken to Track My Request
page with pre-filled EID.
d. On this screen, the resident will be able to download the card by clicking on Download My VID card
button on the bottom left corner of the screen.
e. The downloaded card will be a password protected PDF. The residents can view the downloaded VID card by entering the password combination displayed on the screen.
View VID number: All the VID numbers will be masked by default. The residents can view the unmasked version of VID by clicking on eye icon next to the VID number.
On clicking Secure My ID
, the residents can view the status of all the authentication types. They can choose to lock or unlock authentication types like the following:
Email authentication
Mobile authentication
Demographic authentication
Fingerprint authentication
Iris authentication
Face authentication
The residents can perform the following,
View the current status of authentication types: The lock icon on each card indicates the current status of the authentication type. E.g.: If the lock is open, the authentication type is unlocked which means the residents can authenticate themselves using that particular authentication type and vice versa.
Lock/ unlock the authentication types: To lock/ unlock a particular authentication type, the residents can click on lock/ unlock button. Once the preferences of each authentication type is selected, the residents can click on Submit
to save the changes and click Yes
to proceed. Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
On clicking Track My Requests
, the residents can track the status of an EID associated with the logged-in UIN/ VID. They can also view and download the detailed information about the entered EID like:
Event ID- This is the unique ID provided against each event
Event Type- This is the feature that is being availed. E.g.: Lock/unlock authentication types
Event Status- This is the status of the event which can hold values like Success, Failure or In-Progress
Individual ID- This is the type of individual ID that was used to login. E.g.: VID or UIN
Summary- This the the detailed description of the event.
Timestamp- This the time when the event occurred.
Authentication Mode- This is the authentication mode used to login. E.g.: OTP or Biometric or QR code
Partner Logo- This is the logo of the registered partner.
Partner Name- This is the name of the registered partner.
Attribute List- This is the list of attributes shared with the registered partner.
Purpose- This is the purpose of sharing data with the registered partner as input by the resident.
The resident can reach Track My Requests
page by the following ways:
UIN services > View history > Click on the event tile > View details
By clicking the bell icon
UIN services > Track My Requests
Note:
Residents can download their updated UIN /VID card.
Report a grievance: The residents can report a grievance in case of fraud or for any event not initiated by them. On clicking Report an Issue
, the resident will be redirected to the Grievance Redressal Form
page where they will see a set of pre-filled data as well as a set of data to be filled.
On clicking Get Personalised Card
, the residents can select the data to be added to their credential. They can preview the chosen data and download it. To be able to download the card, residents should select at least 3 attributes from the list mentioned below:
Name- Name of the resident. They can choose the format in which they want the name to be displayed.
Date of Birth- Date of birth of the resident. They can choose the format in which they want the date of birth to be displayed.
UIN- Unique Identification Number. They can choose to mask or unmask the UIN.
Perpetual VID- Perpetual Virtual ID. They can choose to mask or unmask the VID.
Phone number- Registered phone number of the resident. They can choose to mask or unmask the phone number.
Email ID- Registered email ID of the resident. They can choose to mask or unmask the email ID.
Address- Address of the resident. They can choose the format in which they want the address to be displayed.
Gender
Photo
These details can be previewed as and when the attributes are chosen.
Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
On clicking Share My Data
, the residents can choose the data to be shared with any of the registered partners to avail various third party services.
To share the data, residents should select at least 3 attributes from the list mentioned below:
Name- Name of the resident. They can choose the format in which they want the name to be displayed.
Date of Birth- Date of birth of the resident. They can choose the format in which they want the date of birth to be displayed.
UIN- Unique Identification Number. They can choose to mask or unmask the UIN.
Perpetual VID- Perpetual Virtual ID. They can choose to mask or unmask the VID.
Phone number- Registered phone number of the resident. They can choose to mask or unmask the phone number.
Email ID- Registered email ID of the resident. They can choose to mask or unmask the email ID.
Address- Address of the resident. They can choose the format in which they want the address to be displayed.
Gender
Photo
These details can be previewed as and when the attributes are chosen.
Additionally, the residents have to:
Select the partner with whom they want to share their data from a dropdown list of registered partners.
Enter the purpose of sharing the data with the registered partner.
On clicking the Share
button, the resident will have to provide consent to share their data with the external partner.
Once the event is completed, a message is displayed containing the Event ID along with a link to track the service.
The Resident Portal menu bar contains the following:
Font Size- Residents can alter the size of the font based on their preferences.
Language- Residents can select the language of preference.
Bell icon Notification- Residents can view the notifications of all the asynchronous events in chronological order.
Profile Icon- Residents can view the following:
Name of the logged in user
Photo of the logged in user
Last login details
Logout option
The residents can use this feature to verify their registered email ID or phone number.
Steps to verify email ID/ phone number:
Resident clicks either on Verify email ID or Verify phone number option
Enter the UIN/VID.
Select I’m not a robot
against the captcha and click on Send OTP
.
Resident enters the OTP received on the requested channel and clicks on Submit
.
Based on the scenario, any of the below three messages will be displayed:
a. Email ID/ phone number successfully verified: On successful verification, a message is displayed on the screen saying that the phone number/ email ID has been successfully verified.
b. Email ID/ phone number was already verified: If the verification has been previously completed, a message is displayed saying the email ID/ phone number was already verified.
c. Email ID/ phone number does not exist: If there is no email ID/ phone number linked to the UIN/VID, a message is displayed saying no email ID/ phone number was found associated to this UIN/VID.
The residents can use this feature for one of the following:
Download their UIN card
Check the status of their Application ID (AID)
Steps to download the UIN:
Resident clicks on Get My UIN
Enter the AID/UIN/VID.
Select I’m not a robot
against the captcha and click on Send OTP
.
Resident enters the OTP received on the registered email ID/ phone number and clicks on Submit
.
The default PDF of UIN card will be downloaded and a success message is seen stating that the UIN has been successfully downloaded.
Steps to check the status of the AID:
Note: If the UIN is not ready, then the AID is used to get status else UIN card will be downloaded using AID too.
Resident clicks onGet My UIN
.
Enter the AID.
Select I’m not a robot
against the captcha and click on Send OTP
.
Resident enters the OTP received on the registered email ID/ phone number and clicks on Submit
.
The status of the AID will be shown.
Residents can view the list of supported documents in the PDF format and download the same. Also, some sample documents are available for reference.
Residents can search for Registration Centres on the basis of below two mechanisms:
Nearby centers: The resident will be asked to allow permission for location access in order to enable the system to suggest the nearest Registration Centres.
Manually look for centers: If the Resident wants to manually look for a center, they can do so by choosing a level in location hierarchy from the drop-down (e.g.: Region, Province, Postal Code) and entering the value against the same.
They can also download the PDF version of the result displayed on the screen for reference.
Resident Service DB Scripts to be run:
The master-data templates required for the Resident portal are added to the and DML excel files in repository. These scripts need to be applied to the corresponding table.
Here is the document which explains how resident-oidc
partner is onboarded through after deployment.
For more details on how to configure the Resident OIDC client, refer .
UIN services using UIN/VID (through ):
The residents can book an appointment for registration using the pre-registration portal. To do so, they can click on Book an appointment
tile which will redirect them to the pre-registration portal. To know more about pre-registration portal, refer to this link .
MOSIP uses Postgres DB for all relational data storage. The DB creation SQL scripts are located under /db_scripts
the folder of the module repository. In sandbox deployment, Postgres is installed as a docker inside the cluster. However, in production deployment, typically, Postgres will be installed external to the cluster.
Entity relationships diagrams for all databases used in MOSIP are given below.
Connection details
{module_name
}_database_url
{module_name
}_database_username
{module_name
}_database_password
Hibernate configurations
javax.persistence.jdbc.driver
hibernate.dialect
hibernate.jdbc.lob.non_contextual_creation
hibernate.hbm2ddl.auto
hibernate.show_sql
hibernate.format_sql
hibernate.connection.charSet
hibernate.cache.use_second_level_cache
hibernate.cache.use_query_cache
hibernate.cache.use_structured_entries
hibernate.generate_statistics
logging.level.org.hibernate.SQL
logging.level.org.hibernate.type
These are some of the reference settings of a production database. It is expected that these are reviewed and finalized for a given deployment.
WebSub provides a common mechanism for communication between publishers of any kind of Web content and their subscribers, based on HTTP web hooks. Subscription requests are relayed through hubs, which validate and verify the request. Hubs then distribute new and updated content to subscribers when it becomes available. WebSub was previously known as PubSubHubbub. For more information, read W3C WebSub.
In MOSIP, WebSub is used to share data with services and partners. Kafka message broker has been used to implement the WebSub APIs. Message brokers are a natural fit for the implementation of WebSub hubs as they serve a similar purpose.
The relationship of WebSub with other services is explained here. NOTE: The numbers do not signify sequence of operations or control flow.
Topic is registered and published or subscribed by MOSIP Services.
Content delivery and Intent Verification is done by WebSub to Mosip Services.
Content delivery and Intent Verification is done by WebSub to Partners.
Topic is registered and published or subscribed by the Partners.
Data and metadata needed for delivery, delivery reports and other functionalities are stored in Kafka.
Refer WebSub repo for further details.
To know more about the developer setup, read WebSub Developers Guide.
Object Store is a storage module for MOSIP named as Khazana. The module is an abstraction of storage layer used across Registration Client, Packet Manager, Datashare or Durian for packets and biometric data.
Khazana provides following adapters to store objects
POSIX - Supports storage of packets on a filesystem. Its typically used by registration client to store packets locally on the machine. This adapter is not receommended for usage in low latency environments like packet manager.
S3 - S3 is one of the well known API for object stores. AWS Java S3 Client is used in Khazana to support any S3 compliant object storage solutions.
Object Store is used for following purpose wihin mosip
Registration Client - Encrypted packets
Pre-registration - Uploaded Documents
Idrepo - Individual's biometrics and documents
Datashare - On demand individual's biometrics, documents and other information.
As part of our sandbox deployment we have provided an example use case with minio for on-prem deployment and AWS S3 with AWS deployment. Object Store is installed as part of default sandbox deployment.
Note: Please note its important to choose the right partner for object storage and work with them to scale acordingly. Please follow the hardware estimate for Object Store based on respective Object store products.
The below is the list of S3 Java API's used by MOSIP. This can be used to understand the vendor compatibility. Khazana does not use any internal business logic and is purely an storage abstraction layer.
WebSub module provides a common mechanism for communication between publishers of any kind of Web content and their subscribers, based on HTTP webhooks.
Below is a list of tools required in WebSub:
Ballerina (Swan-Lake)
Any IDE (like Vs Code)
Kafka
Postman (any HTTP Client)
Git
Download Kafka and install it.
For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.
Open the hub and consolidator folders where Ballerina.toml
is present.
Open the command prompt from the same folder.
Run the command bal build
to build the hub and consolidator.
Open the project in VS Code either by open with vs code
or from File -> Open Folder
.
Run Configure and run Kafka, update KAFKA_BOOTSTRAP_NODE
in Config.toml
to point to your Kafka.
WebSub consists of consolidator and hub.
Consolidator should be started first, Got to consolidator -> java -jar target/bin/<Jarname>
. (Config.toml should be in the same place where you are running this command).
Start WebSub with the same approach.
The APIs can be tried with the help of kernel-websub-api.
This guide helps the operator in setting up the registration client.
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.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 with it's TPM public key.
To onboard the machine and the operator, the Admin needs to:
Create and activate the registration client machine using Admin portal.
Create a user/operator account in Keycloak
Assign the operator a role of either the Supervisor or Officer using the Admin portal.
Finally, perform the User Zone mapping and User Center mapping in the Admin portal.
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]
To setup the registration client:
Download the reg-client.zip
from the hosted server.
Unzip the client. You can see the directory structure below.
Click run.bat
to launch registration client.
The client always launches with the pre-loader screen which displays the information about the network status, build status verification, online status, etc.
First time launch
After the pre-loader, the login screen is displayed.
Any valid operator credentials can be provided to authenticate and start the initial sync.
On successful intial sync, the operator will be prompted to restart the application.
After the first launch, the operator can notice .mosipkeys and db folders created under the registration client setup folder.
Note: Deletion of either the .mopsipkeys or the db folder makes the application get into an invalid state and hence will fail to launch. To be able to launch the client again, the operator should make sure that both the folders are removed and then re-launch the client.
On the next launch after the initial sync,
The registration client login page provides the operator an option to select the language for viewing the registration client UI.
After successful login, the operator either lands into the operator onboard page or the home page.
Offline- Operator can use the registration client in offline mode to only do the registrations and EOD process. During offline mode, the operator authentication will be based on locally saved password hash. An operator can work in offline mode only if they have logged into to the registration client being online atleast once.
Online- Machine must be online for the registration client first launch. For any server-client sync or vice-versa, the registration client must be online. In the online mode, the client reaches out to the server for password authentication.
Note: On successful onboard of the operator, biometric templates of the operator are stored locally. Biometric authentication does not reach out to the server everytime, instead it is validated based on the locally stored templates on the registration client machine.
1. Incorrect username/password
2. Configuration / masterdata Sync failed
Partner management portal allows the partners to register themselves in MOSIP. With LTS release, the following types of partners can register themselves:
Authentication Partners
Credential Partners(with limited features)
Device Providers
FTM Provider
A Partner Admin can create Policies that are required for Authentication and Credential partners. The section below describes the types of policies that are supported by MOSIP.
To create policies, policy groups should be defined. Policy groups can be considered as the regulatory bodies in a country, examples could be Telecom, Insurance, Banking, etc.
Login as Partner Admin
into the PMS portal.
After successful login, on the left navigation pane, click on Policy -> Policy Group.
The existing policy groups are listed on the screen and the new ones can be created.
To create Policy groups
Click Policy -> Policy Group -> +Create Policy Group
Enter the Policy group Name and Description and click Save.
To search or filter any data pertaining to policy groups, use the filter menu.
You can also change the status of policy group(Deactivate/Re-activate) or edit it using the Action menu as shown below.
On successful creation of Policy groups, polices can be created under that group. MOSIP supports two types of policies, i.e., Auth policy and Datashare policy.
Click Auth Policy -> Create Policy.
Add the Name and Description.
From the dropdown, select the Policy group.
Add the Policies Data.
Click Save.
Note: Once the policy is created, it will be in Inactive state. You have to activate it before using it for a partner.
Select the policy you want to activate or edit.
From the Actions menu, select Activate/Edit.
Use the filter menu.
Data Share policy can be created/edited in the same way as the steps mentioned in the previous section on Auth policy
by using Data Share Policy menu options.
Partners in MOSIP are created in a self-service mode. The partner visits the MOSIP partner management portal and requests for collaborating with MOSIP by providing basic details such as organization name and email-id, purpose of registration (how they want to collaborate with MOSIP - as a device provider, authentication partner, print partner, etc), basic credentials and performing an OTP based verification. Once these details are filled by the partner and a request is sent to MOSIP, the Partner Admin
verifies the details of the partners and allows the partner to integrate with MOSIP.
To know more about each of the partners, click:
Java API Used by MOSIP | S3 Documentation URL |
---|---|
Download Ballerina and install it as per instructions. (Use bal -v
to ensure installation and version).
Copy websub-service.toml
and websub-consolidator.toml
file from mosip-config repository to hub and consolidator folder respectively and rename both of them as Config.toml
(case-sensitive).
To extract the TPM public key, use the .
For more details on operator onboarding, refer to .
For more details on Home page, refer to .
In the development environment, Registration client can be tested using mock SBI. Find the instructions to build and run the mock SBI, click .
Partner Type | Associated Role |
---|
By default, on clicking Auth policy, the screen displays the list of existing auth .
getConnection(bucketName).getObject(bucketName, finalObjectName)
getConnection(bucketName).getObjectMetadata(bucketName, finalObjectName)
doesBucketExistV2(bucketName)
createBucket(bucketName)
getObjectMetadata()
getObjectMetadata().getUserMetadata()
addUserMetadata(m.getKey(), m.getValue())
PutObjectRequest(bucketName, finalObjectName, s3Object.getObjectContent(), objectMetadata)
getRequestClientOptions()
setReadLimit(readlimit)
putObject(putObjectRequest)
deleteObject(bucketName, objectName)
listObjects(account, searchPattern)
getObjectSummaries()
listObjects(searchPattern)
getObjectSummaries()
doesObjectExist(bucketName, finalObjectName)
GetObjectTaggingRequest(bucketName,finalObjectName)
getObjectTagging(getObjectTaggingRequest)
SetObjectTaggingRequest(bucketName,finalObjectName,objectTagging)
setObjectTagging(setObjectTaggingRequest)
Partner Admin | PARTNER_ADMIN |
Policy Manager | POLICYMANAGER |
Authentication Partner | AUTH_PARTNER |
Credential Partner | CREDENTIAL_PARTNER |
Device Provider | DEVICE_PROVIDER |
FTM Provider | FTM_PROVIDER |
This guide describes the various functions provided in the Home page of the reference UI implementation of the registration client.
The Registration Client menu bar displays the following:
MOSIP logo
Home button
Logged in username
Center name
Machine name
Server connection status symbol (shows if the client is online or offline)
Breadcrumbs (User Guide/Reset Password/Logout)
Synchronize data is the data required to make the Registration Client(RC) functional. Full sync is performed initially during the launch of the RC for the first time. Post this, the RC syncs only the changes from sever and this is called as the delta sync. Synchronize data is automated and can be triggered manually. This happens automatically while launching the RC and is also manually initiated by the operator.
Configuration sync: Sync of properties which drives in deciding the RC UI functionality. For example: Invalid login attempts, idle timeout, thresholds, etc.
Masterdata sync : As a part of this sync, supporting information like Dynamic fields data, templates, locations, screen authorization, blocklisted words, etc. are pulled in.
UserDetails sync: userID, along with their status is synced. Only the user details belonging to machine mapped center will be synced.
Certificate sync: Certificates used to validate the server signatures, device CA certificates, public key (specific to a center and machine, also called as policy key) used to encrypt the registration packet will be synced.
Packet sync:
All the approved/rejected Registration IDs(RIDs) will be synced to the server.
All the synced RID packets will be uploaded to the server.
All the uploaded packet status will be synced from server.
An operator can download the pre-registration data of a machine mapped center while being online 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. Provided the machine is online, any pre-registration application can be downloaded irrespective of the center booked by the resident.
This pre-registration data is downloaded from pre-registration API as an encrypted packet and stored in the local storage.There is a batch job running in background for deleting the pre-registration packets after configurable number of days.
Note- Date Range of pre-registration data to be downloaded and storage location of pre-registration data in the registration machine is configurable. Also, this is synced as a part of configuration sync.
Using this option, the operators can onboard themselves anytime.
For more details, refer Operator Onboarding Guide.
Application upload refers to upload of supervisor reviewed registration packets (approved and rejected). From this page, the operator can export the packets to any location on their machine on clicking Save to Device button.
Upload of registration packet from this page internally performs two operations in sequence:
Sync registration metadata to server
On successful sync of metadata, actual registration packets are uploaded to the server.
Client Status: This column displays the status of a registration packet based on the above mentioned operation.
APPROVED
REJECTED
SYNCED
EXPORTED
Server Status:
On success,
PUSHED
PROCESSED
ACCEPTED
On failure,
REREGISTER
REJECTED
RESEND
This column displays the type of registration packet (New packet, Lost packet, Update packet, Correction packet)
When a machine is re-mapped from one center to another center, all the pending activities in the machine related to the former center needs to be completed.
On successful completion of pending tasks, the former center's details will be deleted from the local Derby DB and a full sync will be initiated to pull in the new center details.
Packet Approvals/rejections
Packet upload
Server confirmation on receiving a packet
Deletion of packets after receiving a confirmation
Deletion of pre-registration packets
Deletion of center specific data like the public/policy key
Note- After completing the above tasks, a restart will be prompted to initiate the full sync with new center details.
Clicking on this button, triggers a check for any new client version availability in the upgrade server.
The machine must be online to be able to check updates.
If there is any new version available, a confirmation pop-up is displayed to the operator for starting the upgrade or a reminder is displayed.
The operator can initiate any task from amongst- New registrations, Update UIN, Lost UIN, Correction flow. To get started, the operator needs to select a language for data entry. The number of languages displayed in the UI is configurable and depends on the country.
An operator can initiate the process of registering a new applicant in the MOSIP ecosystem by filling the new registration form with the resident.
Below are few of the processes that needs to be completed for a new registration.
Capture consent- For every registration, the registration client provides an option for the operator to mark an individual's consent for data storage and utilization.
Enter demographic data and upload documents If the resident has a pre-registration application ID, the operator can auto-populate the demographic data and the documents by entering the pre-registration ID. If the resident does not have a pre-registration ID, the operator can enter the resident’s demographic details (such as Name, Gender, DOB, Residential Address, etc.) and upload the documents (such as Proof of Address, Proof of Identity, Proof of Birth) based on the ID Schema defined by the country.
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. 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.
After the timeout has occurred and the captured quality of biometrics is less than the threshold, registration client provides an option to re-try 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 operator can mark that particular biometrics as exception but the operator has to capture the resident's exception photo.
What is the difference between an adult' and an infant' biometric capture?
For an adult, all the configured biometrics can be captured.
For an infant, by default, only the face biometrics is allowed to be captured.
Concept of biometric exception
Permanent or temporary missing / defective fingers or irises can be marked as exception during registration process.
Marked exception finger / iris names are sent as part of rcapture
request to SBI.
A photo of resident is captured highlighting his/her biometric exceptions called as Proof of exception (POE).
Biometric exception photo is captured by the biometric face camera device.
Until 1.2.0, POE was collected only as documentType
field. From 1.2.0.1, Captured biometric exception photo is stored in the biometric data file (CBEFF xml file).
When a resident visits the registration center to update their demographic or biometric details, the operator captures the updated data as provided by the resident in the registration client. The resident needs to give their UIN and also select the field(s) that needs an update. The image below gives an idea of the update UIN process Flow in the registration client.
The UIN update feature is configurable by a country. The Admin can turn ON or OFF, the UIN update feature using the configuration.
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 the demographic details of the individual and processes a request to retrieve the lost UIN. As biometrics play a crucial in identifying a person's identity, it is mandated to provide the biometrics as a part of the Lost UIN flow. Other details like demographic data, uploading documents are optional.
As a part of Lost UIN flow, the contact details like the phone number/ e-mail address of the UIN holder can also be updated and stored in the ID Repository based on the value provided for the property (uingenerator.lost.packet.allowed.update.fields) which is specified in the Registration Processor properties.
If the value already exists for the above mentioned property and once the lost UIN is found, details corresponding to the property value can be fetched from Packet manager and updated in ID Repository.
Example: uingenerator.lost.packet.allowed.update.fields= phone,email
For a resident whose UIN is yet not generated, they can get a request intimation to re-provide their details with a RequestId. The same AddtionalInfo RequestId must be provided to the operator during the correction flow.
Note- The above mentioned Registration tasks are completely configurable through UI Specs<>
The operator can preview the data filled and navigate back to the respective tabs in case of corrections.
Once the resident and the operator are satisfied with the data being captured, the operator can proceed to the Authenticate tab and provide his valid credentials to mark the complete of the registration task.
Once the registration process (new registration, UIN update or lost UIN, correction) is completed, the registration client generates an acknowledgement receipt. This receipt contains a QR code of the Registration application ID, captured demographic data in the selected language, 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.
The image below is that of a sample acknowledgement receipt.
The Supervisor has the exclusive authority to approve/reject packets. The supervisor is supposed to manually re-verify the registrations before uploading them to the server. This page enables them to perform this activity.
Steps to approve/reject packets
Click on any of the registrations listed in the left pane. The registration details are displayed on the right pane.
Supervisor needs to manually verify all the details in the right pane.
Supervisor can click Approve/Reject button based on their verification.
To mark the completion of this approval process, they need to click on Authenticate and provide their credentials.
On successful authentication, approved/rejected packets will be removed from here and be seen on the Application Upload page.
All the registrations which are being marked with the RE-REGISTER status is listed here.
On clicking Dashboard, the Registration client dashboard HTML template is rendered. Default dashboard displays information about the operator, Packets and the Sync Activities.
This section has been reserved for the countries to be able to display their live news and updates. This can be implemented as per a country's requirements.
During the training of the Operators, It must be ensured that consent is obtained directly from the resident whose personal information is being collected and processed. There is no technical way to handle this scenario, so the operator training must include this activity as a manual process and emphasize upon strictly following the same.