National ID client
Business functionality associated with a National ID client and instructions to setup a MOSIP enabled National ID integration.
Last updated
Business functionality associated with a National ID client and instructions to setup a MOSIP enabled National ID integration.
Last updated
Civil registration provides the source of truth for any vital event that occurs in a country. As a result is usual that an integration with a country's National ID system is requested.
We have some default functionality and some functionality that is unique to integrations with .
When creating a National ID client, you must give it a name. If you are installing OpenCRVS alongside MOSIP, enter "MOSIP" (without quotation) for the name, otherwise you can give it any name you like and take advantage of the default functionality explained below.
You can only have one National ID client!
Currently OpenCRVS supports the following default National ID integration functionality:
OpenCRVS can let a National ID system know of any birth that occurs in the country so that operations can be put in place to provide a National ID number for the child.
OpenCRVS can let a National ID system know of any death that occurs in the country so that operations can be put in place to invalidate a National ID number for the deceased.
OpenCRVS can let MOSIP know of any birth that occurs in the country so that operations can be put in place to provide a National ID number for the child. MOSIP integration requires installation assistance from our core team.
OpenCRVS can let a National ID system know of any death that occurs in the country so that operations can be put in place to invalidate a National ID number for the deceased.
When a MOSIP enabled National ID client is set up, at the point of death, the deceased's National ID number must be captured in the application form.
If there is any failure communicating with MOSIP, the event creation will not be interrupted in OpenCRVS. This is to ensure that civil registration still occurs regardless of the current health of the MOSIP installation.
If you are integrating with MOSIP, there are a few extra configuration steps in OpenCRVS that are required when setting up your servers and deploying.
You will need to copy the secret key files that MOSIP will provide you with onto your server in this directory. The names of these files must match whatever you use in docker-compose in the next step.
A MOSIP supplied secret key. It will look something like this: "rosxZG5q..."
A MOSIP supplied secret key. It will look something like this: "123..."
A MOSIP supplied secret key. It will look something like this: "rosxZG5q..."
There are many other use cases that can be considered for future development of a more fully featured National ID integration with OpenCRVS such as:
Validation: Validating all supplied National ID numbers with a National ID system before application submission and pre-populating CR application forms with demographic data returned by the NID system for informants and parents.
Revocation: Occasionally a death may be wrongly registered either fraudulently or by mistake. Any revocation in OpenCRVS should be communicated to the National ID system.
We are continually improving our National ID integration capabilities and look forward to addressing functionality such as this in future versions of OpenCRVS. For more information, please get in touch at: team@opencrvs.org
The default functionality dispatches the full payload at the moment of registration via the same process utilised by the webhook client. You can consider the National ID client as identical to a client with full payload permissions. To implement the National ID client, you must configure a webhook mediator service in exactly the same way for any other client.
Example code for a mediator service that subscribes to an OpenCRVS National ID webhook is our
MOSIP functionality contains the default functionality with some extra functionality unique to MOSIP requirements. For a detailed explanation refer to the .
The will return a unique token (UINTOKEN) that will be saved into the child's FHIR Patient details as an additional identifier. This token is unique for the individual for life. In this way it can be used when the individual dies to connect the birth and death event together and invalidate a death.
The will also return an application ID (MOSIP_AID) that can be printed on a birth certificate using the certificate handlebar {{mosipAid}}. A baby is too young for biometrics to be captured in National ID processing, but this application ID allows the child's National ID application to be retrieved in the future and converted into a MOSIP National ID (VID / UIN) at any time.
The deceased's National ID number (VID / UIN) is sent in a request to the (details below). . OpenCRVS then uses the UINTOKEN to link the death with the birth event before dispatching the death webhook.
Refer to the to prepare MOSIP for OpenCRVS integration.
When setting up your OpenCRVS servers, you may need to provision a Wireguard VPN, and you will need a shared Docker volume to store some secret key files that MOSIP will supply you with. You will need to uncomment before running the Ansible command in .
Before you deploy, you will need to copy the block from this demo docker-compose file into one of the docker-compose files relevant for your deployment (e.g. staging, qa or production)
Either add a block to docker-compose to host the within the OpenCRVS stack, or alternatively host the Mediator on MOSIP's Kubernetes architecture making use of the Wireguard VPN. MOSIP can provide more support regarding this step.
When deploying OpenCRVS alongside MOSIP, the MOSIP team will provide you with a few extra secrets that are referenced in docker compose and supplied by deployment scripts in environment variables from Terminal. The following secrets must be added to your Github or exported as environment variables when to your server.
OSIA support: In 2023 we plan to support an National ID integration.
