Technical interoperability

By using FHIR as a standard for our NoSQL datastore Hearth and interoperability layer OpenHIM, OpenCRVS seamlessly connects civil registration to health services and other systems. We can receive birth and death notifications from the hospital setting and expose registration events to any other technical system, such as National ID, via our FHIR standard API gateways in OpenHIM.

To interact with the OpenHIM Gateway as an external system, your system administrator is required to:

  1. SSH into the OpenCRVS manager node and register a new system client
  2. Securely host the system client_id, client_secret and sha_secret, returned in the registration process, as environment variables or Docker Secrets that your mediator or webhook subscriber service has secure access to.

You are then required to:

  1. Authenticate and request an access token. Described below.
  2. Develop a mediator or webhook subscriber to perform your required business functions. We expose some OpenCRVS events as Webhooks which can be a good way to interact immediately if the supported events are of interest to you.

Register a system client

In the upcoming OpenCRVS Beta release the following process will be deprecated and replaced by a form in the System Administrator User Team Management functionality.

Using a valid system administrator JWT token returned during OpenCRVS client authentication, SSH into your manager instance and run the following commands to register a new client.

Find a running auth service Docker container ID. NOTE: You may need to connect to a worker node if auth is not running on the manager.

docker ps -a
docker exec <Insert auth service container id on node> \
wget -S --header="Authorization: Bearer <Insert your valid system administrator JWT here>" \
--header='Accept-Charset: UTF-8' --header='Content-Type: application/json' \
--post-data ‘{"scope":"NATIONAL_ID"}' \
-O - http://user-mgnt:3030/registerSystemClient

Request payload

Example json

{
"scope": "NATIONAL_ID",
}
ParameterSample valueDescription
scopeNATIONAL_IDAvailable integration scopes currently include: NATIONAL_ID HEALTH AGE_CHECK EXTERNAL_VALIDATION.

Request Response

The command will return the following details:

{
"client_id": "2fd153ab-86c8-45fb-990d-721140e46061",
"client_secret": "8636abe2-affb-4238-8bff-200ed3652d1e",
"sha_secret": "d04aec67-1ef4-467a-a5a8-fa5c89ad71ce"
}

These are your authentication, and webhook payload verification details for your API and should be stored securely in line with your organisation's security policies and never exposed in code repositories.

ParameterSample valueDescription
client_id2fd153ab-86c8-45fb-990d-721140e46061The client id used in the authentication process for system clients.
client_secret8636abe2-affb-4238-8bff-200ed3652d1eThe client secret used in the authentication process for system clients.
sha_secretd04aec67-1ef4-467a-a5a8-fa5c89ad71ceThe SHA1 signature used when verifying that a webhook payload is genuine

Deactivate a system client

Using a valid system administrator JWT token returned during OpenCRVS client authentication, SSH into your manager instance and run the following commands to deactivate an existing client:

Find a running auth service Docker container ID. NOTE: You may need to connect to a worker node if auth is not running on the manager.

docker ps -a

Run the following command replacing the client_id with the client_id you wish to deactivate. You can browse the user-mgnt > systems collection in Mongo to find the client details.

docker exec <Insert auth service container id on node> \
wget -S --header="Authorization: Bearer <Insert your valid JWT here>" \
--header='Accept-Charset: UTF-8' --header='Content-Type: application/json' \
--post-data '{"client_id":"2fd153ab-86c8-45fb-990d-721140e46061"}' \
-O - http://user-mgnt:3030/deactivateSystemClient

Reactivate a deactivated system client

Using a valid system administrator JWT token returned during OpenCRVS client authentication, SSH into your manager instance and run the following commands to reactivate a previously deactivated client:

Find a running auth service Docker container ID. NOTE: You may need to connect to a worker node if auth is not running on the manager.

docker ps -a

Run the following command replacing the client_id with the client_id you wish to reactivate. You can browse the user-mgnt > systems collection in Mongo to find the client details.

docker exec <Insert auth service container id on node> \
wget -S --header="Authorization: Bearer <Insert your valid JWT here>" \
--header='Accept-Charset: UTF-8' --header='Content-Type: application/json' \
--post-data '{"client_id":"2fd153ab-86c8-45fb-990d-721140e46061"}' \
-O - http://user-mgnt:3030/reactivateSystemClient

Request an access token

URL

POST https://auth.<your-open-crvs-host.com>/authenticateSystemClient

Request payload

Example json

{
"client_id": "2fd153ab-86c8-45fb-990d-721140e46061",
"client_secret": "8636abe2-affb-4238-8bff-200ed3652d1e"
}
ParameterSample valueDescription
client_id2fd153ab-86c8-45fb-990d-721140e46061The client id used in the authentication process for system clients.
client_secret8636abe2-affb-4238-8bff-200ed3652d1eThe client secret used in the authentication process for system clients.

Request Response

{
"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
}

The token is a JWT containing with the following structure and must be included as an Authorization: Bearer <token> in all future requests:

Token Header

ParameterSample valueDescription
algRS256Signing algorithm.
typJWTThis value is always JWT.

Token Payload

ParameterSample valueDescription
scope['health']An array of OpenCRVS roles for authorization permissions to access. These are defined as a feature of the OpenCRVS core. Approved scopes are health, nationalId, ageCheck. If you require a new scope, please open a feature request
iat1593712289When the JWT was created.
exp1594317089When the JWT expires - For System clients this is set to 10 minutes by default, but this is configurable in the resources package.
aud['opencrvs.auth']An array of services that will respond to this JWT.
iss'opencrvs.auth'The issuing service of the JWT.
sub'5ee75eb2104ccf88d9ac0c3d'Equal to the user or system id.

Interoperability via OpenHIM and FHIR

OpenHIM is our pass-through, publish/subscribe middleware for all civil registration process events, tracking and exposing them as Webhooks, via authenticated API integrations - OpenHIM Mediators.

FHIR was created by Health Level Seven International (HL7) a not-for-profit, ANSI-accredited standards developing organization dedicated to providing a comprehensive framework and related standards for the exchange, integration, sharing and retrieval of electronic health information that supports clinical practice and the management, delivery and evaluation of health services.

We designed FHIR standards for Civil Registration and look forward to submitting them to HL7 for inclusion in the next version of FHIR.

Example integrations

Mediators can be built in any technology due to being containerised microservices, and can convert in real-time, any data format to and from FHIR and we have an example of these integrations into DHIS2 and National ID in operation in Bangladesh.

A simple mediator exposing the age of a child to a 3rd party application, (in this case a Telegram / WhatsApp chatbot used to verify if a child is old enough to be married) is available here.

You can read more about the functional interoperability requirements here

You can read more regarding record verification here

Coming August 2020

OpenCRVS will be publishing documentation on this site of an integration showcasing standards-based interoperability between the civil registration function of OpenCRVS and identity management systems (both functional and foundational).

This will include:

This interoperability is very important to ensure that the legal identity established at birth is then utilised as a foundational identity to access other services (e.g. health, education, financial inclusion, passport, mobile phone etc.) and to ensure that we leave no one behind.

You can view work-in-progress documentation of our approach here: